Common Errors by Feature

Transfers

Error	HTTP Status	Cause	Resolution
bank_code is required	422	Missing bank code	Include bank_code in request
account_number must be 10 digits	422	Invalid account length	Verify account number is exactly 10 digits
Insufficient balance	400	Wallet balance too low	Fund wallet before retrying
Duplicate reference	406	Same ref used for a previous transfer	Use a unique ref per transfer
Minimum amount is 100	406	Transfer amount below NGN 100	Increase amount to at least NGN 100
Invalid bank code	400	Bank code not in supported list	Fetch bank list from GET /payouts/bank/list

Virtual Accounts

Error	HTTP Status	Cause	Resolution
customer_id is required	400	Missing customer identifier	Pass customer_id in request body
Account type not supported	400	Invalid account_type value	Use static or dynamic
Invalid bank	400	Unsupported bank provider	Use 9psb, palmpay, or cashconnect
BVN is required for Palmpay	400	PalmPay static accounts need BVN	Include identity_type and identity_number
Amount exceeds maximum	400	Dynamic VA amount > NGN 1,000,000	Reduce amount or use a static account
Expiry out of range	400	Duration outside 15 min – 24 hrs	Adjust expiry parameters

Cards

Error	HTTP Status	Cause	Resolution
ref is required	400	Missing idempotency key	Include a unique ref in request
KYC level not met	422	Customer hasn't completed KYC Level 2	Upgrade customer KYC tier first
Maximum of 3 active cards can be created for a user.	403	Business already has 3 active cards	Freeze or terminate an existing card
Insufficient balance	400	Wallet balance too low for card funding	Fund the business wallet
Invalid card type	400	Unsupported card type	Use virtual or physical

Bills Payment

Error	HTTP Status	Cause	Resolution
ref is required	400	Missing idempotency key	Include a unique ref
Amount out of range	400	Amount outside biller's allowed range	Check biller product for min/max amounts
Invalid meter number	400	Electricity meter number format invalid	Verify meter number with the biller
KYC level not met	422	KYC Level 2 required for electricity	Upgrade customer KYC tier

Authentication

Error	HTTP Status	Cause	Resolution
Unauthorized	401	Missing API key	Add Authorization: Bearer ps_pk_test_... or ps_pk_live_... header for the matching environment
Invalid API key	401	API key is wrong or expired	Generate a new key from Settings > API Keys
Forbidden	403	Key lacks required permissions	Check key permissions in the dashboard

Rate Limiting

Error	HTTP Status	Cause	Resolution
Too many request	429	More than 60 POST requests per minute from one source IP	Implement exponential backoff in your client

General

Error	HTTP Status	Cause	Resolution
Something went wrong	500	Unexpected server error	Retry with the same ref; contact support if it persists
Not found	404	Resource doesn't exist	Verify the ID or reference is correct
Validation failed	422	Request body fails validation	Check the errors object for field-specific details

See the Errors reference for HTTP status code descriptions.