Reference
Errors
Every error code the API returns, with its HTTP status.
Every error answers with the same object:
{ "error": { "code": "INVALID_REQUEST", "message": "…", "request_id": "…", "details": { } } }Branch on code, never on message (wording may change). Quote request_id to support. details is present when there is more to say, for example the invalid fields.
| Code | HTTP status | Meaning |
|---|---|---|
INVALID_REQUEST | 400 | Invalid request |
AUTHENTICATION_FAILED | 401 | Authentication failed |
PERMISSION_DENIED | 403 | Permission denied |
MERCHANT_NOT_ACTIVE | 403 | Merchant account is not active |
NOT_FOUND | 404 | Resource not found |
CONFLICT | 409 | Conflict |
IDEMPOTENCY_CONFLICT | 422 | Idempotency key was reused with a different request |
RATE_LIMITED | 429 | Too many requests |
PAYLOAD_TOO_LARGE | 413 | Payload too large |
INVALID_STATE_TRANSITION | 409 | Operation not allowed in the current state |
REFUND_CAP_EXCEEDED | 422 | Refund amount exceeds the refundable balance |
LEDGER_INVARIANT_VIOLATION | 500 | Internal ledger error |
SETTLEMENT_INTEGRITY_VIOLATION | 422 | Settlement item does not match the batch |
ATTEMPT_NOT_ALLOWED | 409 | A new payment attempt is not allowed in the current state |
CAPTURE_POLICY_VIOLATION | 409 | Capture not allowed |
VOID_NOT_APPLICABLE | 409 | This payment was never authorized at the provider; there is nothing to void |
IMMUTABLE_RECORD | 409 | Record is immutable |
PROVIDER_UNAVAILABLE | 502 | Payment provider unavailable |
PROVIDER_TIMEOUT | 504 | Payment provider timed out |
SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable |
INTERNAL_ERROR | 500 | Internal error |