Error Codes
Common Ivorypay API error codes and recovery guidance.
errorCode is present on many failures, but is not guaranteed on every response. Handle HTTP status and a missing code as well. These are common codes; use Errors and safe retries for handling timeouts and uncertain payment outcomes.
Error response format
{
"success": false,
"message": "Human-readable description",
"statusCode": 400,
"errorCode": "ONOFFRAMP0033",
"errors": [],
"timestamp": "3/26/2026, 12:00:00 PM",
"path": "/api/v1/endpoint",
"method": "POST"
}Authentication & Authorization
ONOFFRAMP0017
No authorization header
401
Request was sent without an Authorization header
ONOFFRAMP0018
Provide a Bearer token
401
JWT route received a value without the Bearer prefix
ONOFFRAMP0019
No API key provided
401
API key route received no credential
ONOFFRAMP0022
(passes through underlying cause, e.g. jwt malformed)
401
Generic auth failure wrapper: message carries the underlying reason
ONOFFRAMP0032
Access denied
403
Authenticated but not permitted for this resource
Bank & Account Errors
ONOFFRAMP0033
Invalid bank code. Please provide a valid bank code
400
The bankCode doesn't match any supported bank
ONOFFRAMP0056
Unable to validate account details provided
400
Account lookup/validation failed
ONOFFRAMP0087
Invalid bank id. Please provide a valid bank id
400
The bank ID doesn't exist
ONOFFRAMP0088
We can't verify this bank account right now. Please try again later.
400
Bank account resolution failed
MANSA0049
Blockchain account not found
404
No blockchain account record for the lookup
MANSA0089
Your Duffle is at capacity with 5 saved bank accounts. Please remove one to add another.
409
Saved-bank-account limit reached
MANSA0090
Bank details not found
404
No saved bank details for this identifier
MANSA0091
This bank account is already saved in your Duffle
409
Duplicate bank details entry
MANSA0092
Bank not found for the given currency
404
No bank in our directory for that fiat currency
MANSA0093
We couldn't create a new wallet address right now. Please try again soon.
503
Blockchain address provisioning failed: retry later
Customer Errors
ONOFFRAMP0053
Customer not found
404
No customer with the given ID, email, or refCode
Transaction Errors
ONOFFRAMP0048
Transaction not found
404
No transaction with the given reference/ID
ONOFFRAMP0049
Invalid transaction
400
The transaction is in a state that does not allow this operation
ONOFFRAMP0050
Reference must be a valid UUID
400
The reference query/path parameter is not a UUID
ONOFFRAMP0054
Duplicate transaction
409
A transaction with the same reference already exists
ONOFFRAMP0055
Unable to process fiat payment
400
Fiat-leg processing failed
ONOFFRAMP0065
The minimum amount you can <feature> is <amount> <currency>
400
Amount is below the minimum for the feature/currency
ONOFFRAMP0066
Offramp is not enabled for this business
403
Off-ramp feature is not activated for the business
ONOFFRAMP0067
Onramp is not enabled for this business
403
On-ramp feature is not activated for the business
ONOFFRAMP0069
Transaction session not found
404
The session identifier does not exist
ONOFFRAMP0070
Session cannot be refreshed more than 5 times, please initiate a new transaction
400
Session refresh limit hit
ONOFFRAMP0071
This business does not have support for this fiat currency. Please contact support
400
The merchant is not enabled for the requested fiat currency
ONOFFRAMP0092
Transaction source already exists
409
The transaction-source record already exists for this merchant
Wallet & Payout Errors
ONOFFRAMP0081
Wallet not found
404
No wallet for the resolved business/currency
ONOFFRAMP0083
Not enough funds in your wallet. Please add more to continue.
400
Insufficient balance for the operation
ONOFFRAMP0091
A request with the reference exist
409
Duplicate payout request
Webhook Errors
ONOFFRAMP0051
Webhook not found
404
No webhook matches the given ID
ONOFFRAMP0052
You have aleady set up a webhook for your <env> environment
409
One webhook per environment per business
General Errors
ONOFFRAMP0000
Internal server error
500
Unexpected error: contact Ivorypay support
Validation failures
Validation can return HTTP 400 or 422. The errors value can be a field-keyed object rather than an array. A safe diagnostic may also include errorCode: "INVALID_REQUEST_DATA", attemptId, and reference. Do not assume every field is present.
Check the endpoint's required fields, enum values and amount units. Correct the request before retrying. Never log API keys, identity documents or full payment request bodies.
Recovery
401/403: check the product key, environment and account access.404: check the reference and the business/environment that created it.409: read the existing request before deciding what to do; a duplicate reference is not an instruction to create another payment.429: honourRetry-Afterwhen provided and use backoff.5xx/ timeout: a payment may already have been accepted. Reconcile its status using the original reference before another initiation.
Failure codes can also describe payment-stage errors, such as invalid request data or unavailable pricing. Show the returned safe message and retain the attempt/reference identifiers for support. Do not derive a balance or insufficient-funds conclusion from a generic error.
Last updated