Concepts

Errors

Stable machine codes, human messages, and the details to fix it.

Error shape

{
  "error": {
    "code": "kyc_fields_missing",
    "message": "Before a NGN account can be issued for Adaeze Okafor, we need:",
    "details": ["BVN (required by Nigerian banking partners)"]
  }
}

Field	Type	Description
validation	400	A field is missing or malformed. details lists each problem.
environment_mismatch	401	Sandbox key against production URL, or the reverse.
missing_scope	403	The key lacks the scope this endpoint needs.
forbidden	403	The authenticated role can't perform this action.
not_found	404	No such resource in this environment.
idempotency_conflict	409	Idempotency-Key reused with a different payload.
corridor_disabled	422	This corridor direction isn't enabled for your account — e.g. NGN international payouts.
insufficient_balance	422	The balance doesn't cover amount plus fee. Nothing was held.
customer_not_approved	422	Accounts can only be issued to approved customers.
issuance_limit	422	Environment account limit reached; contact support to raise it.
rate_limited	429	Too many requests. Honor Retry-After.