Error handling
Every error the gateway returns to callers, what it means, whether you were charged, and how to recover.
On this page
Error shape
Gateway errors are JSON with an error code, and sometimes more fields. Branch on error. Every gateway response has Cache-Control: no-store.
{ "error": "upstream_failed", "reason": "status_500", "upstreamStatus": 500 }The directory and pricing APIs use a different shape; see API reference conventions.
Were you charged?
Only a successful answer with a PAYMENT-RESPONSE header can mean money moved. Every error below means your payment was not submitted, except settlement_failed and settlement_unavailable, where the provider was already called; see the table.
Error codes
| Status | error | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_path | A path segment is ., .., or contains /, \ or a NUL after decoding. | Fix the path. |
| 400 | invalid_payment_header | PAYMENT-SIGNATURE isn't base64 JSON with accepted.extra.memo and payload.transaction. | Fix the header. |
| 400 | invalid_payment | The transaction can't be decoded or has no token transfer. | Rebuild the payment. |
| 402 | payment_required | No payment was sent. A quote is attached. | Pay the quote. |
| 402 | a rejection reason | The payment was rejected, for example payment_expired, unknown_quote, quote_already_used, exposure_cap_exceeded or a verification code. A new quote is attached. | Fix the cause, then pay the new quote. |
| 404 | unknown_api | No live API has this slug. It may be paused. | Check the slug in the directory. |
| 405 | method_not_allowed | The API doesn't accept this method. See Allow. | Use an allowed method. |
| 409 | payment_already_processed | This exact payment was already used. Includes its state. | Don't resend it. Check the earlier answer. |
| 409 | payment_in_progress | Another request with this payment is being served. | Wait for that request. |
| 409 | payment_not_ready | The payment is in a state that can't be served. | Request a new quote. |
| 413 | request_too_large | The body is over 1 MiB. | Send less. |
| 429 | rate_limited | Too many quotes from your address. | Wait Retry-After seconds. |
| 502 | upstream_failed | The provider failed (reason: network, too_large) or its answer wasn't billable (reason such as status_500 or empty_body, with upstreamStatus). The provider's body is withheld. Not charged. | Retry later with a new quote, or choose another API. |
| 504 | upstream_failed | The provider didn't answer within 20 seconds (reason: timeout). Not charged. | Retry later with a new quote. |
| 502 | settlement_failed | The provider answered but the payment couldn't be settled on-chain. The answer is withheld. Not charged. | Retry with a new quote. |
| 503 | price_change_in_progress | The provider is changing the price. Retry-After: 30. | Wait, then request a new quote. |
| 503 | payment_verification_unavailable | NODRA couldn't reach Solana to check the payment. | Retry the same signed payment after Retry-After. A new transaction for this quote will be refused. |
| 503 | settlement_unavailable | The provider was called but settlement couldn't start. NODRA keeps retrying while your transaction is still valid. | Don't pay again. Check later with the receipt or your wallet. |
| 503 | payment_core_unavailable | A temporary NODRA outage. On the paid attempt, the payment may already have been used. | Resend the same payment after Retry-After. A 409 means it was used: check your wallet before paying again. |
| 500 | internal_error | An unexpected NODRA error. | Retry later. |
Retry rules
- Same payment, again: safe after
payment_verification_unavailableorpayment_core_unavailable. Never charges twice. - New quote, new payment: only after an error that says you weren't charged, such as
upstream_failed,settlement_failedor a402rejection. - Wait and check: after
settlement_unavailableor a network error on the paid attempt, check your wallet's recent transactions before paying again.