Errors

Errors return JSON with a human-readable message and a stable machine-readable code:

{
  "message": "An active subscription is required to use the payment API.",
  "code":    "subscription_required"
}

Validation errors also include an errors object keyed by field name:

{
  "message": "The amount field is required.",
  "code":    "validation_error",
  "errors": {
    "amount": ["The amount field is required."]
  }
}

Error codes

HTTP	Code	Meaning
401	`authentication_error`	Missing, invalid, revoked, or expired API key.
402	`subscription_required`	No active subscription.
402	`transaction_limit_reached`	Monthly plan transaction limit used up.
403	`merchant_suspended`	Account suspended — contact support.
403	`ability_denied`	The API key does not have the required ability for this endpoint (see API keys).
403	`website_not_allowed`	Browser request blocked — no websites are registered, or this origin is not in your registered websites.
404	`http_error`	Unknown payment reference (or owned by another merchant).
409	`duplicate_invoice_number`	A payment already exists for this `invoice_number` and hasn't failed or expired — see Idempotency.
422	`validation_error`	Validation failed; see the `errors` object.
429	`http_error`	Rate limited (120 requests/minute per key).

Payment failure reasons

Failed payments carry a failure_reason: duplicate_trx_id (the TrxID was already used to verify another payment) or rejected_by_admin (manually rejected after review).