Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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"
}

timestamp is a locale-formatted string from Date.toLocaleString() on the server, not ISO 8601.

Authentication & Authorization

Error Code
Message
HTTP Status
Description

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

Error Code
Message
HTTP Status
Description

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

Error Code
Message
HTTP Status
Description

ONOFFRAMP0053

Customer not found

404

No customer with the given ID, email, or refCode

Transaction Errors

Error Code
Message
HTTP Status
Description

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

Error Code
Message
HTTP Status
Description

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

Error Code
Message
HTTP Status
Description

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

Error Code
Message
HTTP Status
Description

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: honour Retry-After when 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