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. Honour Retry-After.
  • 5xx — our problem. Retry with the same reference.

Codes you may see

  • missing_bearer_token / invalid_api_key
  • wrong_environment — a sandbox key on a live-only endpoint, or the reverse
  • merchant_not_approved — live money movement needs an approved merchant application
  • invalid_body, invalid_idempotency_key, invalid_period
  • idempotency_conflict — the same key or reference with a different body
  • collection_not_found, charge_not_found, transfer_not_found, payout_not_found
  • refund_not_allowed — the collection is not in a refundable state
  • rate_limited
  • verification_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.