Error Handling

Response envelopes

Success:

{
  "status": true,
  "message": "Order created",
  "data": { }
}

Error:

{
  "status": false,
  "code": "E_VALIDATION_ERROR",
  "message": "Exactly one of from.amount or to.amount must be provided"
}

Some authentication failures use "status": "failed" on HTTP 401/403.

Status	Meaning	Action
`200`	Success	Process `data`
`400`	Bad request	Fix payload
`401`	Unauthorized	Check credentials / signature
`403`	Forbidden	KYB not approved, or IP whitelist
`404`	Not found	Verify reference
`422`	Validation error	Fix fields
`429`	Rate limited	Retry with backoff
`5xx`	Server error	Retry with idempotency

Log code, message, and your merchant_reference
Do not retry 4xx except 429
Treat timeouts as ambiguous — query by merchant_reference before creating another order