Skip to content
Sign in
Menu

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.

JSON
{ "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

StatuserrorMeaningWhat to do
400invalid_pathA path segment is ., .., or contains /, \ or a NUL after decoding.Fix the path.
400invalid_payment_headerPAYMENT-SIGNATURE isn't base64 JSON with accepted.extra.memo and payload.transaction.Fix the header.
400invalid_paymentThe transaction can't be decoded or has no token transfer.Rebuild the payment.
402payment_requiredNo payment was sent. A quote is attached.Pay the quote.
402a rejection reasonThe 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.
404unknown_apiNo live API has this slug. It may be paused.Check the slug in the directory.
405method_not_allowedThe API doesn't accept this method. See Allow.Use an allowed method.
409payment_already_processedThis exact payment was already used. Includes its state.Don't resend it. Check the earlier answer.
409payment_in_progressAnother request with this payment is being served.Wait for that request.
409payment_not_readyThe payment is in a state that can't be served.Request a new quote.
413request_too_largeThe body is over 1 MiB.Send less.
429rate_limitedToo many quotes from your address.Wait Retry-After seconds.
502upstream_failedThe 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.
504upstream_failedThe provider didn't answer within 20 seconds (reason: timeout). Not charged.Retry later with a new quote.
502settlement_failedThe provider answered but the payment couldn't be settled on-chain. The answer is withheld. Not charged.Retry with a new quote.
503price_change_in_progressThe provider is changing the price. Retry-After: 30.Wait, then request a new quote.
503payment_verification_unavailableNODRA 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.
503settlement_unavailableThe 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.
503payment_core_unavailableA 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.
500internal_errorAn unexpected NODRA error.Retry later.

Retry rules

  • Same payment, again: safe after payment_verification_unavailable or payment_core_unavailable. Never charges twice.
  • New quote, new payment: only after an error that says you weren't charged, such as upstream_failed, settlement_failed or a 402 rejection.
  • Wait and check: after settlement_unavailable or a network error on the paid attempt, check your wallet's recent transactions before paying again.