Error Handling

All errors follow a consistent format. The success field is always false on errors.

Error Format

Error response

{
  "success": false,
  "error": "Human-readable error message"
}

details is optional and only present when extra context is available, such as per-field validation errors on a 400 response.

Code	Description
`400`	Bad request — invalid input, invalid JSON body, or payment method not enabled
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — account is pending admin approval
`404`	Not found — resource does not exist
`409`	Conflict — merchantOrderId already exists for your account
`500`	Server error — something went wrong on our end
`502`	Bad gateway — the payment provider returned an error

400 — Invalid input

{
  "success": false,
  "error": "Invalid input",
  "details": { "fieldErrors": { "amount": ["Expected number, received string"] } }
}

403 — Pending approval

{ "success": false, "error": "Account pending approval" }

409 — Duplicate order

{ "success": false, "error": "merchantOrderId already exists" }

502 — Provider error

{ "success": false, "error": "Payment provider error: ..." }