Failed requests
What happens to a payment when authorization is invalid, verification fails, the upstream times out or errors, or settlement fails.
On this page
Summary
| Failure | Caller sees | Provider called | Charged |
|---|---|---|---|
| Invalid authorization (bad header or transaction) | 400 invalid_payment_header or invalid_payment | No | No |
| Verification fails | 402 with the reason and a new quote | No | No |
| Quote expired | 402 with payment_expired | No | No |
| Upstream times out (20 s) | 504 upstream_failed, reason: timeout | Yes | No |
| Upstream error or unbillable answer | 502 upstream_failed with reason and upstreamStatus | Yes | No |
| Settlement fails | 502 settlement_failed, answer withheld | Yes | No |
| Settlement can't start | 503 settlement_unavailable | Yes | Possibly, once NODRA's retry succeeds |
Authorization is invalid
If the PAYMENT-SIGNATURE header can't be decoded or lacks the memo or transaction, the gateway answers 400 invalid_payment_header. If the transaction can't be decoded or has no token transfer, 400 invalid_payment. Nothing is recorded against the quote, so you can fix the payment and send it for the same quote while it's valid.
Verification fails
The payment is recorded as rejected and the gateway answers 402 with the reason in error (for example a policy code such as policy_program_not_allowed, an x402 verification code, or exposure_cap_exceeded) and a fresh quote. The rejected quote is used up. If NODRA can't reach Solana to verify, it answers 503 payment_verification_unavailable instead, and the quote isn't used up.
The upstream times out
If the provider doesn't finish answering within 20 seconds, the payment becomes upstream failed, the reservation is released, and the gateway answers 504 with {"error":"upstream_failed","reason":"timeout"}. The transfer is never submitted.
The upstream returns an error
A non-2xx status, a redirect, an answer over 1 MiB, or a 2xx that doesn't meet the billing rule is not billable. The gateway answers 502 with the reason (such as status_404, empty_body or json_field_missing) and upstreamStatus, and withholds the provider's body. The transfer is never submitted.
Settlement fails
If Solana definitively rejects the transfer after the provider answered (for example, the payer's balance changed), the gateway answers 502 settlement_failed and withholds the provider's answer. The payment is recorded as settlement failed; the caller isn't charged and the provider isn't paid.
If the signing service or payment core can't be reached at that moment, the gateway answers 503 settlement_unavailable. NODRA keeps retrying settlement in the background while the transaction is still valid, so the payment may still settle. Check the transaction or your wallet before paying again.