Error codes

Errors use the standard envelope:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount must be an integer in kobo",
    "field": "amount"
  }
}

Code	HTTP status	Meaning
VALIDATION_ERROR	400	Request input failed validation
INVALID_REFERENCE	400	Payment reference format is invalid
GATEWAY_NOT_FOUND	400	Requested gateway is unknown or unavailable
GATEWAY_DISABLED	400	Gateway is disabled for this account
INVALID_WEBHOOK_SIGNATURE	400	Incoming processor signature verification failed
UNAUTHORIZED	401	Authentication is missing or invalid
INVALID_API_KEY	401	API key is malformed, unknown, or revoked
KYC_REQUIRED	403	A Live operation requires approved KYC
BUSINESS_RESTRICTED	403	Business status blocks this operation
FORBIDDEN	403	Authenticated principal lacks permission
PAYMENT_NOT_FOUND	404	Payment is absent from this business and environment
NOT_FOUND	404	Requested resource does not exist
PAYMENT_ALREADY_PROCESSED	409	Transaction is already in a terminal state
DUPLICATE_PAYMENT	409	Idempotency key cannot be reused for this request
KEY_LIMIT_REACHED	409	Five active keys already exist in the environment
PAYMENT_EXPIRED	410	Hosted payment link has expired
WEBHOOK_TEST_RATE_LIMITED	429	Endpoint exceeded the test-event limit
NO_GATEWAY_AVAILABLE	503	No eligible payment processor is currently available

Use error.code for branching and error.message for a safe human-readable explanation. Do not write logic that depends on exact message wording.

Retry network errors and selected 5xx responses with bounded exponential backoff. Do not automatically retry validation, authentication, or authorization failures without correcting the request.