Errors
Stable error envelopes for every REST endpoint.
Public errors return a safe type, code, message and request_id. The request id should be logged by integrators and support teams.
Error envelope
{ "error": { "type": "validation_error", "code": "invalid_request", "message": "Invalid request payload.", "request_id": "req_xxx", "issues": [] }}Error types
| Field | Type | Description |
|---|---|---|
authentication_error | 401 | Missing, malformed or invalid API key. |
permission_error | 403 | The key is valid but does not include the required permission. |
validation_error | 400 | The request body, path or query parameters are invalid. |
idempotency_error | 409 | The Idempotency-Key was reused with a different request. |
not_found_error | 404 | The resource does not exist in the current API key scope. |
rate_limit_error | 429 | The integration exceeded the configured rate limit. |
configuration_error | 400 | The platform configuration is incomplete for this operation. |
api_error | 5xx | Unexpected platform or downstream failure. |
Common codes
| Field | Type | Description |
|---|---|---|
invalid_api_key | auth | The Authorization header is missing or invalid. |
insufficient_permissions | authz | The key cannot perform this action. |
invalid_request | validation | The payload failed schema validation. |
raw_card_not_allowed | PCI | Raw card data was sent to a non-tokenization endpoint. |
pricing_plan_not_configured | config | The platform has not configured its pricing plan for this method/installments yet. |
idempotency_key_conflict | retry | The same key was used for a different operation. |
internal_error | server | Unexpected failure; use request_id when contacting support. |