Error Model

All API errors follow a normalized structure so your client can implement consistent retries, alerting, and user messaging regardless of upstream provider.

Standard Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "currency is required",
    "details": {
      "field": "currency"
    }
  }
}

Common Error Codes

Code	Meaning
`AUTH_INVALID_CREDENTIALS`	Invalid app keys or token
`AUTH_TOKEN_EXPIRED`	Access token expired; refresh or re-authenticate
`VALIDATION_ERROR`	Invalid request payload or missing required fields
`PAYMENT_NOT_FOUND`	Unknown payment reference
`PAYMENT_NOT_REFUNDABLE`	Payment cannot be refunded in current state
`RATE_LIMIT_EXCEEDED`	Request rate exceeded, retry later
`IDEMPOTENCY_PAYLOAD_MISMATCH`	Idempotency key reused with different payload
`PROVIDER_UPSTREAM_ERROR`	Connected payment provider failed upstream

Handling Guidance

Retry only retryable classes (timeouts, 429, upstream transient errors).
Do not retry validation or authorization failures without correction.
Log error.code and request correlation IDs for support escalation.