Error codes

The error object#

{
  "error": {
    "code": "PAYMENT_DECLINED",
    "message": "The payment was declined by the payment provider.",
    "decline_reason": "insufficient_funds",
    "request_id": "req_7Hc2LqP",
    "doc_url": "/errors#payment-declined"
  }
}

• code — stable identifier to branch on.
• message — human-readable, may change. Don’t parse it.
• request_id — include it when contacting support.

Error reference#

{
  "error": {
    "code": "PAYMENT_DECLINED",
    "decline_reason": "insufficient_funds",
    "request_id": "req_7Hc2LqP"
  }
}

{
  "error": {
    "code": "CARD_EXPIRED",
    "request_id": "req_2Pb8XwQ"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "param": "amount",
    "message": "amount must be an integer."
  }
}

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "request_id": "req_9Qd1MnZ"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "param": "id"
  }
}

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "request_id": "req_4Tr6VbS"
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 2
  }
}

{
  "error": {
    "code": "PROVIDER_UNAVAILABLE",
    "routing": { "attempts": 2 }
  }
}

Payments and order error catalog#

This catalog restores the complete set of stable codes from the previous public response-code reference. Current codes were cross-checked against the payment and order API code paths; legacy-only codes remain listed for backward compatibility. Messages may vary; branch on the code rather than parsing message text.

Orders and checkout

Order lifecycle, checkout readiness, payment links, files and request handling.

Payments

Payment validation, processing, authentication, transaction operations and provider responses.

Merchant order responses

Errors returned while validating merchant order, fulfillment and coupon responses.

Anti-fraud

Stable fraud-evaluation errors returned with payment and order operations.

Handling errors#

1. Branch on error.code; log request_id.
2. Retry 5xx and 429 with backoff and the same Idempotency-Key.
3. Never retry 400, 401 or 402 unchanged.