Errors
Every error code the API returns, grouped by resource, and which ones are safe to retry.
A failed request returns status: false, an error message, and a stable code.
Match on code, and display error to people.
{
"status": false,
"error": "Quote lapsed or already used. Get a new one.",
"code": "quote_expired"
}
A 404 response does not reveal whether another business owns the resource.
| HTTP | What to do |
|---|
400, 404 | Fix the request. Sending it again unchanged returns the same error. |
403 | Your API key cannot make this change. Ask a dashboard admin to make it. |
409 | The request conflicts with the current state. Follow the cause in the tables below. |
429 | Wait 60 seconds, then retry. |
500, 503 | Retry with the same body and the same reference. See Idempotency. |
| HTTP | Code | Cause |
|---|
| 400 | bad_request | Malformed JSON, a missing required field, or an invalid field format. |
| 401 | unauthorized | Invalid or missing API key. |
| 429 | rate_limited | Too many requests. Wait 60 seconds before retrying. |
| 503 | service_unavailable | An upstream service was unreachable and nothing was written. Retry. |
| 500 | internal | Unexpected failure. Safe to retry with the same reference. |
| HTTP | Code | Cause |
|---|
| 400 | amount_required | The request sends both source_amount and destination_amount, or neither. |
| 400 | invalid_amount | The amount is outside the amount limits. |
| 400 | invalid_currency | Both currencies are NGN, or neither is. |
| 400 | invalid_asset | The crypto is not a supported asset. |
| 400 | invalid_network | The network is not supported for that asset. |
| 400 | partner_fee_exceeds_cap | The partner fee is above your account's cap. |
| 400 | partner_fee_wallet_missing | You have no fee wallet for the payout network. Add one under Fees in the dashboard. |
| 404 | quote_not_found | The quote does not exist for your business. |
| 409 | quote_not_refreshable | The quote already created an order, so it cannot be refreshed. |
| HTTP | Code | Cause |
|---|
| 400 | quote_expired | The quote expired, or it already created an order. Get a new one. |
| 400 | quote_flow_mismatch | An onramp quote was used on an offramp order, or the reverse. |
| 400 | invalid_destination_address | The address is not valid for the quoted network. |
| 400 | account_verification_failed | The bank could not confirm the beneficiary account. |
| 400 | recipient_id_required | Your business pays out only to its own accounts. Send recipient_id, not beneficiary or destination. |
| 400 | recipient_id_not_supported | Your business pays its customers. Send beneficiary or destination, not recipient_id. |
| 400 | recipient_not_found | recipient_id does not match one of your payout accounts. |
| 400 | recipient_type_mismatch | An offramp order named a wallet, or an onramp order named a bank account. |
| 400 | recipient_quote_mismatch | The wallet's network or stablecoin differs from the onramp quote's. |
| 404 | order_not_found | The order does not exist for your business. |
| 409 | duplicate_reference | The reference belongs to a different order. |
| 409 | quote_changed | A refresh changed the quote during order creation. |
| HTTP | Code | Cause |
|---|
| 400 | invalid_recipient | The request has no object matching type, or sends another account object with it. |
| 400 | account_verification_failed | The bank could not verify the account. Check the bank code and account number. |
| 400 | invalid_destination_address | The wallet address is not valid for its network. |
| 400 | invalid_type | The type filter on GET /v1/recipients is not a supported type. |
| 403 | payout_accounts_locked | Your business pays out only to its own accounts. Ask a dashboard admin to make the change. |
| 404 | recipient_not_found | The payout account does not exist for your business. |
| 409 | recipient_in_use | A collection or an unfinished order still uses this account. |
| HTTP | Code | Cause |
|---|
| 400 | recipient_not_found | recipient_id does not match one of your payout accounts. |
| 400 | recipient_type_mismatch | The new recipient_id on PATCH /v1/collections/{id} is a different kind of payout account from the collection's. |
| 400 | invalid_type | The type filter on GET /v1/collections is not a supported type. |
| 400 | invalid_status | The status filter on GET /v1/collections is not active or disabled. |
| 403 | payout_accounts_locked | Your business pays out only to its own accounts. Ask a dashboard admin to change the collection's recipient_id. |
| 404 | collection_not_found | The collection does not exist for your business. |
The deposit simulator has its own codes. See
Simulator errors. In the live environment, the simulator
returns 404 simulation_disabled.