Errors

A failed payment is not an HTTP error

This is the distinction that matters most. If a customer’s payment is declined, the request still succeeds: you get a 2xx, and the failure is described inside the resource, on the attempt’s failure block. An HTTP error means Orchestrate could not process your request — bad credentials, invalid input, a resource that does not exist. Handle the two separately.

{
  "failure": {
    "code": {
      "value": "...",
      "category": "CUSTOMER_ERROR",
      "message": "..."
    },
    "message": "..."
  }
}

Failure categories

Every payment failure carries a category. Branch on the category, not on the individual code: codes are added over time, categories are stable.

Category	What it means	What to do
`CUSTOMER_ERROR`	The customer can fix it — wrong code, insufficient balance, cancelled.	Show the message and let them try again.
`GATEWAY_ERROR`	The provider failed or was unavailable.	Transient. Retrying later is reasonable.
`TELCO_ERROR`	The mobile network operator failed.	Transient. Retrying later is reasonable.
`MERCHANT_CONFIG_ERROR`	Your project configuration cannot serve this payment.	Fix it in your dashboard; retrying will not help.
`PLATFORM_ERROR`	Something went wrong on the Orchestrate side.	Contact support with the payment id.
`SECURITY_ERROR`	The payment was blocked by an integrity or fraud control.	Do not retry programmatically.

HTTP status codes

Status	Meaning
`200`	Success.
`201`	Resource created.
`401`	No key, or the key is invalid, inactive or expired.
`403`	The request address is not on the key’s IP allowlist.
`404`	The resource does not exist, or is not visible to this key’s environment.
`409`	Conflict — most often a payout `reference` you have already used.
`422`	The request was well-formed but rejected: validation failed, the intent is already final, or the service declined the refund or payout.
`429`	Rate limit exceeded. Back off and retry.
`5xx`	Server error. Retry with backoff; use an idempotency key so the retry is safe.

Error shape

Errors carry a human-readable message. Validation errors add a field-by-field breakdown.

{
  "message": "The given data was invalid.",
  "errors": {
    "currency": ["The currency field must be 3 characters."]
  }
}

Show message to your operators, not to your customers — for customers, use the failure.code.message on the attempt, which is written for them.

Retrying safely

429 and 5xx are worth retrying with exponential backoff. For 429, respect the Retry-After header and the operation-specific rate limit. Always send an idempotency key on the original request so the retry cannot create a second payment. 4xx other than 429 will not succeed on retry. Fix the request first.

Get started

Payments

Payouts

Events

Utilities

MCP

A failed payment is not an HTTP error

Failure categories

HTTP status codes

Error shape

Retrying safely

​A failed payment is not an HTTP error

​Failure categories

​HTTP status codes

​Error shape

​Retrying safely

A failed payment is not an HTTP error

Failure categories

HTTP status codes

Error shape

Retrying safely