Developer docs
Errors
Every error comes back in the same shape, so your integration can handle them the same way everywhere.
The envelope
JSON
{
"error": "This reference was already used for a different charge. Use a new reference.",
"code": "idempotency_conflict"
}error is a human-readable sentence — safe to show a developer, never safe to branch on. code is the stable, machine-readable value. Branch on the code.
Status codes
400— the request body or query is invalid.401— missing or unknown API key.403— the key is not allowed to do this: wrong environment (a sandbox key on a live endpoint) or a KYB gate that is not cleared.404— not found for this key. If a resource exists but belongs to another merchant, you get a 404, not a 403.409— a state conflict: a reference reused with a different body, a refund of something already refunded, a release of something already released.422— the request is well formed but the business rule refuses it (a payout with no revenue account, a verification the rail rejected).429— rate limited. HonourRetry-After.5xx— our problem. Retry with the same reference.
Codes you may see
missing_bearer_token/invalid_api_keywrong_environment— a sandbox key on a live-only endpoint, or the reversemerchant_not_approved— live money movement needs an approved merchant applicationinvalid_body,invalid_idempotency_key,invalid_periodidempotency_conflict— the same key or reference with a different bodycollection_not_found,charge_not_found,transfer_not_found,payout_not_foundrefund_not_allowed— the collection is not in a refundable staterate_limitedverification_failed— the rail could not confirm the account or BVN
Rate limits
60 requests per minute per key by default (configurable to 600). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
Retry rules
- Retry 429 and 5xx with the same reference.
- Never retry 400, 401, 403, 404, 409 or 422 — the request is the problem.
- If you are not sure whether a request went through, read it back with
GET /collections/{reference}before sending it again.
Still stuck? The assistant in the corner of the docs page can look up an endpoint, read the live pricing and build you a request — or leave your details and a human will pick it up. See the quick reference for every endpoint.