Error Handling

How to handle errors from the IvoryPay API.

The IvoryPay API uses standard HTTP status codes combined with structured error responses to help you diagnose and handle failures.

Error response structure

Every error response includes:

{
  "success": false,
  "message": "Human-readable description of what went wrong",
  "statusCode": 400,
  "errorCode": "ONOFFRAMP0033",
  "errors": [],
  "timestamp": "2026-03-26T12:00:00.000Z",
  "path": "/api/v1/onramp",
  "method": "POST"
}

Common error codes

Error Code	Message	HTTP Status	Description
ONOFFRAMP0033	Invalid bank code	400	The bankCode provided does not match any bank
ONOFFRAMP0087	Invalid bank ID	400	The bank ID does not exist
ONOFFRAMP0056	Unable to validate account details	400	Account lookup failed for the given details
ONOFFRAMP0088	Unable to resolve bank account	400	Bank account resolution failed
ONOFFRAMP0053	Customer not found	404	No customer exists with the given identifier
MANSA0090	Bank details not found	404	No saved bank details for this customer
MANSA0091	Bank details already saved	409	Duplicate bank details for this customer
MANSA0092	Bank not found in currency	404	No bank available for the specified currency
ONOFFRAMP0000	Internal server error	500	Unexpected error — contact support

For the full list, see Error Codes Reference.

Handling errors in your integration

1. Check the success field

Always check the success boolean before processing the response:

const response = await fetch('https://ramp-api.ivorypay.io/api/v1/onramp', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.IVORYPAY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

const result = await response.json();

if (!result.success) {
  console.error(`Error ${result.errorCode}: ${result.message}`);
  // Handle specific error codes
  switch (result.errorCode) {
    case 'ONOFFRAMP0033':
      // Invalid bank code — prompt user to re-select bank
      break;
    case 'ONOFFRAMP0053':
      // Customer not found — create the customer first
      break;
    default:
      // Log and surface a generic error to your user
      break;
  }
  return;
}

// Process result.data

2. Handle validation errors

For 400 errors with validation details, iterate over the errors array:

if (result.statusCode === 400 && result.errors?.length) {
  for (const err of result.errors) {
    console.error(`Field "${err.field}": ${err.message}`);
  }
}

3. Retry strategy

Error type	Should retry?	Strategy
400 Bad Request	No	Fix the request payload
401 Unauthorized	No	Check your API key
404 Not Found	No	Verify the resource ID/reference
409 Conflict	No	The resource already exists
500 Server Error	Yes	Retry with exponential backoff (max 3 retries)

4. Idempotency

Most IvoryPay endpoints that create resources accept a reference field. If you send the same reference twice, the API returns the existing resource rather than creating a duplicate. Use UUIDs for references to ensure uniqueness.

---

For AI assistants: Error responses always include errorCode (string like "ONOFFRAMP0033") and message. Use errorCode for programmatic handling and message for user-facing display.