Error Reference

Error response format

All errors follow a consistent JSON structure:

{
  "statusCode": 400,
  "message": "Human-readable description of the error",
  "error": "Bad Request"
}

For validation errors, message may be an array of field-level messages:

{
  "statusCode": 400,
  "message": [
    "phone must be 11 digits",
    "amount must not be less than 50"
  ],
  "error": "Bad Request"
}

Code	Name	When it occurs
`200`	OK	Request succeeded
`201`	Created	Resource created (e.g. access request submitted)
`400`	Bad Request	Invalid request body, failed validation, or business logic error
`401`	Unauthorized	Missing, invalid, or revoked API key
`403`	Forbidden	Action not permitted for your account tier or status
`404`	Not Found	The requested resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	An unexpected error on our side

Message	Cause	Fix
`Unauthorized`	Missing or invalid API key	Check your `Authorization` header
`API access is only available to Tier 3 users`	Account not yet Tier 3	Complete verification to upgrade
`No approved API client found`	Access request not approved	Submit an access request from your dashboard
`Your API key is not active`	Key revoked or disabled	Regenerate your API key

Message	Cause
`Phone number must be 11 digits`	`phone` field format invalid
`minimum amount is N50`	`amount` below minimum
`maximum amount is N10000`	`amount` above maximum
`Webhook must be a valid HTTPS URL`	`webhookUrl` not HTTPS
`Maximum of 20 IP entries`	IP allowlist limit reached

Message	Cause
`Insufficient wallet balance`	Not enough funds in wallet
`Invalid transaction PIN`	Wrong PIN supplied
`Product not found`	Network/product name unrecognized
`Meter number validation failed`	Meter number incorrect or service unavailable
`Smartcard validation failed`	Decoder number incorrect

Message	Cause
`Invalid OTP`	Wrong or expired OTP entered
`OTP has expired`	OTP not used within the time window (10 minutes)
`Too many OTP attempts`	OTP locked after repeated failures