Skip to main content
The API uses conventional HTTP status codes and a JSON body. A 2xx means success; 4xx means the request was rejected; 5xx means a server error.

​
Error shape

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount must be at least 1."]
  }
}
message is always present. errors is included on validation failures and maps each rejected field to its messages.

​
Status codes

CodeMeaning
200 / 201Success.
400 / 422Validation error — see errors.
401Missing, invalid or expired API key.
403Not allowed to perform the action.
404Resource not found.
428Idempotency key required or invalid.
429Rate limited — see Rate limits.
501Endpoint not yet available (manual capture, reconciliation report).
5xxServer error — safe to retry.

​
Payment failures are not request errors

A 4xx/5xx means the request failed. A payment declined by a gateway is not an HTTP error: the request succeeds, and the failure is reported on the attempt’s failure object (code + a human-readable message). See Payment status.

​
With the PHP SDK

Errors map to typed exceptions (all implement OrchestrateException): authentication, permission, not-found, invalid-request (with errors), idempotency, rate-limit, not-implemented, server and connection errors. See SDK error handling.