Skip to content
Sign in
Menu

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

1. Classify the answer

TypeScriptclassify.ts
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

MistakeFix
Signing a new payment after a timeout on your sideResend the same payment first; a new one is a new charge.
Treating 402 after paying as successIt's a rejection with a reason. Read error.
Ignoring settlement_pending receiptsYou got the answer; the payment is still being confirmed. Don't pay again.