Debug quote and route issues
How to debug 0Pools unavailable quotes, expired quotes, conflicts, access errors, stuck trades, and reconciliation gaps.
Debug 0Pools from public evidence first: endpoint, environment, request id, pool id, quote id, trade id, side, amount, network, status, and timestamp. Do not ask developers or users to reason about private routes.
Debug decision tree
Common cases
| Symptom | Likely area | First action |
|---|---|---|
| Pool missing | Entitlement. | Check key mode and allowedPools. |
available: false | Runtime liquidity/pricing. | Read unavailableReason. |
| Firm quote expires quickly | Expected TTL. | Refresh quote; improve UX timer. |
409 on transact | Expired/consumed/reservation conflict. | Retrieve quote/trade by id. |
402 | Prefunded balance. | Check funding and ledger. |
403 | Account/KYC/tier/pool gate. | Fix partner configuration. |
429 | Velocity/rate limit. | Stop retry loop; escalate if limit needs change. |
| Stuck reserved | Settlement/status path. | Alert support with trade id. |
| Ledger mismatch | Reconciliation join. | Compare order, quote, trade, balance, event ids. |
Support packet
{
"environment": "sandbox",
"endpoint": "POST /v1/pools/EUR-USDT/transact",
"partner_reference": "partner_order_123",
"pool_id": "EUR-USDT",
"quote_id": "pq_test_123",
"transact_id": "txn_test_456",
"side": "on_ramp",
"amount": "100.00",
"network": "tron",
"status": "reserved",
"request_id": "req_...",
"timestamp": "2026-06-28T17:00:00Z"
}Never include secret keys, webhook secrets, raw bank payloads, identity files, or private route guesses.
User-safe messages
| Technical state | User-safe message |
|---|---|
pool_dry | "This route is unavailable right now." |
| expired | "Quote expired. Refresh for a new price." |
| insufficient balance | "Top up before transacting." |
| access denied | "This account is not enabled for this flow." |
| reserved | "Settlement is pending." |
| returned | "This transaction is under review." |
Debug layers
Work down the stack in order. If the partner is using the wrong key mode, there is no value in investigating route selection. If the quote expired, there is no value in checking settlement state.
Debug examples
| Report | Likely path | What to collect |
|---|---|---|
| "Pool disappeared from UI." | Entitlement or environment. | Key mode, partner id, GET /v1/pools result, timestamp. |
| "Quote says unavailable." | Runtime quote layer. | Pool id, side, amount, network, unavailable reason, request id. |
| "Accept button fails." | Quote expiry, consumed quote, idempotency, or balance. | Quote id, expiry, idempotency key, error code. |
| "User clicked twice." | Retry/idempotency. | Partner order id, idempotency key, trade ids returned. |
| "Funds pending too long." | Settlement/status layer. | Trade id, current status, created time, last event id. |
| "Finance total does not match." | Reconciliation layer. | Order, quote, trade, ledger, event, request ids. |
Before and after debugging
| Old debugging pattern | 0Pools debugging pattern |
|---|---|
| Ask which provider or route handled the order. | Ask which public object failed: pool, quote, trade, ledger, webhook. |
| Search logs by user name or amount. | Search by request id, quote id, trade id, and partner reference. |
| Retry requests until something works. | Follow quote expiry and idempotency rules. |
| Update user balance manually during investigation. | Keep pending state until terminal status and ledger records agree. |
Escalation rules
Escalate to 0Bit with a complete support packet when:
- repeated unavailable responses affect an approved pool
- a reserved trade exceeds the agreed support window
- terminal status and ledger entries disagree
- webhook signatures verify but expected events are missing
- cross-tenant or unexpected object visibility appears
- the same idempotency key produces an unexpected outcome
Do not escalate with screenshots alone. Always include machine-readable ids and timestamps.
Error-code treatment matrix
Debugging is faster when every error maps to one owner and one user-safe outcome.
| Error class | Likely cause | Partner action | User-safe copy |
|---|---|---|---|
401 | Wrong key, mode mismatch, missing auth. | Check environment and secret handling. | "This service is temporarily unavailable." |
403 | Not entitled, suspended, product not approved. | Refresh access and contact support. | "This route is not enabled." |
404 | Unknown pool, quote, or trade id. | Verify stored ids and environment. | "We could not find this request." |
409 | Idempotency conflict or already-accepted quote. | Reuse correct key or inspect existing trade. | "This request is already processing." |
422 | Invalid amount, side, network, destination. | Fix validation before quote/transact. | "Check the amount or destination." |
5xx | Temporary service failure. | Retry safe reads; retry transact only with same idempotency key. | "Try again shortly." |
Debug packet
{
"environment": "live",
"partner_order_id": "order_7841",
"pool_id": "EUR-USDT",
"quote_id": "pq_live_01J4",
"transact_id": "pt_live_9A2",
"idempotency_key": "order_7841:accept:1",
"request_id": "req_01J4DEBUG",
"observed_error": "409"
}Debug order
Start with environment and entitlement, then quote validity, then idempotency, then status/webhook delivery, then ledger reconciliation. Do not start by guessing route or provider behavior.
Implementation depth
This page is about debugging quote, route, access, status, and reconciliation issues quickly. For developers, the durable boundary is simple: your product should depend on request ids, error codes, unavailable reasons, quote ids, trade ids, status, and event ids; it should not depend on private route selection and source health details. That boundary is what lets 0Pools improve liquidity operations without forcing every partner to rebuild product code.
Product scenario
A user says a quote failed. Support collects the request id, partner order id, pool id, quote type, amount, and response code before escalating.
Before and after in practice
| Before 0Pools | With 0Pools |
|---|---|
| Support starts with screenshots and guesses whether the issue is pricing, auth, liquidity, or ledger state. | Support uses a decision tree based on API layer, object id, and state transition. |
| Product teams infer liquidity behavior from provider-specific screens or manual notes. | Product teams branch on 0Pools objects: pool, quote, trade, balance, webhook, and ledger. |
| Support asks engineering to reconstruct state from logs. | Support starts from request id, quote id, trade id, event id, and ledger id. |
System flow
Records to keep
| Record | Why it matters | Example |
|---|---|---|
request_id | Trace one API call. | req_... |
error_code | Machine-readable branch. | pool_unavailable |
quote_id | Present when quote exists. | pq_test_123 |
transact_id | Present when execution exists. | pt_test_456 |
A useful implementation stores these records before adding optional analytics. Analytics can be rebuilt from durable state; missing ids usually cannot be reconstructed after a customer-impacting failure.
Example product record
{
"product_area": "debug-quote-route-issues",
"partner_reference": "partner_order_123",
"pool_id": "EUR-USDT",
"quote_id": "pq_test_123",
"transact_id": "pt_test_456",
"status": "reserved",
"request_id": "req_01HZY0POOLS",
"reconciliation_state": "open"
}This record is intentionally partner-facing. It references 0Pools objects and your own product ids, but it does not include private liquidity routes, treasury balances, raw provider payloads, or customer secrets.
Failure modes and recovery
| Failure mode | Product response |
|---|---|
| No request id | Log response headers and error envelopes. |
| Retrying validation errors | Fix request fields before retry. |
| Confusing quote with trade | Lookup the right object. |
| Escalating without state | Include status and timestamps. |
Use-case patterns
| Pattern | How 0Pools helps |
|---|---|
| First-line support | Classify the issue in minutes. |
| Engineering debug | Reproduce from request shape. |
| Finance exception | Find missing ledger joins. |
Developer checklist
- Read runtime discovery and capabilities before rendering enabled actions.
- Create firm quotes only when the user is ready to accept the terms.
- Execute from your server with an idempotency key.
- Treat webhooks and status reads as the source of truth for settlement state.
- Reconcile by durable ids first, then by amount and timestamp.
- Do not branch product behavior on provider names, route names, reserve balances, or treasury assumptions.