Card Error Codes

This reference covers card-related error codes you may encounter.

Card creation errors

Error	HTTP status	Cause	Resolution
Name is required	422	No name and no customer ID provided	Provide a customer_id or name
Invalid card type	422	Type is not virtual or physical	Use virtual or physical
User ID (uid) is required for personal card	422	Missing user ID for personal card flow	Include uid in request
Customer ID (cid) is required for business card	422	Missing customer ID for business card flow	Include customer_id in request
Business ID (bid) is required for business card	422	Missing business ID	Include bid in request
Maximum of 3 active cards can be created for a user	403	User already has 3 active cards	Freeze or terminate an existing card first
KYC level not met	422	Customer KYC level is below Level 2	Upgrade customer KYC tier
Insufficient amount to process	403	Wallet balance too low for card creation	Fund the wallet and retry
Please enter a valid top-up value, this must be USD1 and above	422	Top-up amount is below $1	Increase amount to at least $1

Card top-up and withdrawal errors

Error	HTTP status	Cause	Resolution
Amount must be > 0	422	Zero or negative amount	Provide a positive amount
Currency is required	422	Missing currency field	Include currency in request
Currency must match card currency	422	Currency doesn't match card's currency	Use the same currency as the card
Card not found	404	Card ID does not exist	Verify the card ID
Not allowed for this card	403	Business scope mismatch	Ensure the card belongs to your business
Card is terminated	400	Cannot operate on a terminated card	Create a new card
Invalid 2FA code	403	Two-factor authentication failed	Request a new 2FA code

Card management errors

Error	HTTP status	Cause	Resolution
Invalid action	422	Action must be freeze, unfreeze, or terminate	Use one of the valid actions
Type 'TERMINATE' to confirm	422	Confirmation text not provided	Include "TERMINATE" in request body
Enter a valid reason	422	Missing or empty termination reason	Provide a reason for termination
Card not found	404	Card does not exist	Verify the card ID
card_id is required	422	Missing card ID parameter	Include card_id in request
Cannot update contact details for a terminated card	409	Card is already terminated	Create a new card
Customer associated with this card was not found	404	Customer record missing	Verify customer exists
email and mobile are required	422	Missing contact fields	Provide both email and mobile
Card contact update failed — no response from provider	502	Provider did not respond	Retry later
Card contact update failed	400	Provider returned an error	Check response for details

Card balance adjustment errors

Error	HTTP status	Cause	Resolution
Direction must be credit or debit	422	Invalid direction value	Use credit or debit
Amount must be greater than zero	422	Zero or negative amount	Provide a positive amount
Reason is required	422	Missing reason for adjustment	Include a reason string

Common HTTP status codes

Code	Meaning
400	Bad request — invalid parameters
403	Forbidden — permission or KYC issue
404	Resource not found
409	Conflict — card already terminated
422	Validation failed
502	Bad gateway — provider communication error

See the API Errors reference for general API error handling.