Handle failed paid requests
Decide, for each failure, whether you were charged and whether it's safe to pay again.
- Tutorial
On this page
What you'll achieve
A client that never pays twice for one call and recovers cleanly from every gateway error.
Prerequisites
- A working paid request, from Make your first paid API request.
1. Classify the answer
type Next = "done" | "pay-new-quote" | "resend-same-payment" | "check-before-paying" | "stop"
export function nextStep(status: number, error?: string): Next {
if (status < 400) return "done"
switch (error) {
case "payment_verification_unavailable":
case "payment_core_unavailable":
return "resend-same-payment" // never charges twice; a 409 after this means it was used
case "upstream_failed":
case "settlement_failed":
case "price_change_in_progress":
return "pay-new-quote" // not charged; wait Retry-After first where given
case "settlement_unavailable":
return "check-before-paying" // may still settle
case "payment_already_processed":
case "payment_in_progress":
return "stop" // this payment was already used
}
if (status === 402) return "pay-new-quote" // rejected; a fresh quote is attached
return "stop"
}2. Respect Retry-After
429 and 503 answers carry Retry-After in seconds. Wait at least that long.
3. Cap automatic retries
Retry a new quote at most once or twice automatically. Repeated upstream_failed means the API is struggling; try later or choose another.
4. Handle network errors
If the paid attempt's connection drops before you get an answer, resend the same PAYMENT-SIGNATURE. NODRA either continues serving it or answers 409 if it was already used, so you're never charged twice. A 409 means that payment was used and its answer can't be sent again; check your wallet before paying for a new call.
Expected result
Your client pays at most once per successful call and never loses track of a payment.
Common mistakes
| Mistake | Fix |
|---|---|
| Signing a new payment after a timeout on your side | Resend the same payment first; a new one is a new charge. |
Treating 402 after paying as success | It's a rejection with a reason. Read error. |
Ignoring settlement_pending receipts | You got the answer; the payment is still being confirmed. Don't pay again. |