Errors

Errors are returned as a JSON body alongside a non-2xx HTTP status code:

{
  "statusCode": 400,
  "message": "amount must be at least ₦1 (100 kobo)",
  "error": "Bad Request"
}

For request validation failures, message may be an array of every field that failed validation:

{
  "statusCode": 400,
  "message": [
    "email must be an email",
    "amount must not be less than 100"
  ],
  "error": "Bad Request"
}

Common Status Codes

Status	Meaning
`400`	Bad Request — invalid or missing fields, or a business rule was violated (e.g. insufficient balance)
`401`	Unauthorized — missing, invalid, or expired API key
`403`	Forbidden — the action isn't allowed right now: a team-role restriction, a test-mode restriction (e.g. payouts), or a live-mode requirement (e.g. KYB not yet verified)
`404`	Not Found — the resource (session, transfer, product, etc.) doesn't exist for your account
`409`	Conflict — a resource with that identifier already exists (e.g. a duplicate `reference`)
`410`	Gone — the resource is no longer valid (e.g. an expired invite link)
`429`	Too Many Requests — see Rate Limits
`502`	Bad Gateway — the upstream payment processor failed or timed out. Safe to retry.

Always check message for the specific reason — the status code narrows the category, but message tells you exactly what went wrong.