Errors and failure codes

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "body.currency: unsupported currency",
    "param": "currency",
    "details": [
      { "path": "currency", "message": "unsupported currency", "code": "custom" }
    ]
  },
  "request_id": "req_0uwP4ioIZ8q8dgBW"
}

{
  "id": "pay_Bu0waXeXrCN5FbyPnbzy",
  "status": "failed",
  "failure": {
    "code": "stolen_card",
    "category": "hard",
    "message": "Stolen card, pick up"
  },
  "route": {
    "provider": { "code": "demo_acquirer_a", "name": "NATIO Demo Acquirer A" },
    "attempts": 1,
    "rule": "Cards → Acquirer A, fallback Acquirer B"
  }
}

const res = await fetch("https://api.natio.me/v1/payments", init);
const body = await res.json();

if (!res.ok) {
  // Transport-level error: the payment was not created.
  switch (body.error.code) {
    case "idempotency_in_progress":
      return retryShortly();                 // the first call is still running
    case "rate_limited":
      return backOff(res.headers.get("x-ratelimit-reset"));
    case "validation_failed":
      throw new BugInOurCode(body.error.details);
    default:
      throw new NatioError(body.error, body.request_id);
  }
}

// The call succeeded. The payment may still have failed.
if (body.status === "failed") {
  switch (body.failure.category) {
    case "hard":
      return declineCheckout(body.failure.code);   // never retry this instrument
    case "policy":
      return escalate(body.failure.code);          // configuration or risk, not the customer
    default:
      return offerAnotherMethod(body.failure.code); // soft / technical: already cascaded
  }
}