Error model

Handled errors use the envelope below. Messages/details vary by endpoint; legacy middleware can return a simpler error or an empty response. Check HTTP status and parse defensively. These codes reflect payment initiation and setup handlers, not a universal provider error taxonomy.

Standard error response

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

Common error codes

Common error codes
Code	Meaning
`UNAUTHORIZED`	Invalid app credentials, inactive app or authentication required
`FORBIDDEN`	The authenticated actor cannot access this resource
`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
`INITIATION_UNAVAILABLE`	Reservation or saved response unavailable; preserve the same key
`INTERNAL_ERROR`	Request processing unavailable; preserve the original payment identity
`WEBHOOK_TEST_FAILED`	Check the selected app’s HTTPS/signing configuration and recipient acknowledgement
`SANDBOX_REQUIRED`	Use the sandbox environment for a measured first-payment trial

Handling guidance

For initiation timeouts, 429 or 5xx, retain the original key and payload. Correct authorization/validation before retrying; HTTP 202 is reserved execution, not permission to create another payment.
Do not retry validation or authorization failures without correction.
Log error.code and request correlation IDs for support escalation.