API Error Handling & Codes
Our API uses standard HTTP status codes to indicate the success or failure of a request. For client-side errors (4xx) and server-side errors (5xx), the response body will contain a JSON object with a specific errorCode and a descriptive message.
Example Error Response
{
"success": false,
"message": "External reference already in use.",
"errorCode": "DUPLICATE_EXTERNAL_REFERENCE"
}
Common Errors
These are general errors that can be returned by multiple API endpoints.
| HTTP Status | Error Code | Description |
|---|---|---|
| 403 Forbidden | USER_NOT_ONBOARDED | The user's account has not completed the required onboarding or approval process to use this feature. |
| 409 Conflict | DUPLICATE_EXTERNAL_REFERENCE | The externalReference provided has already been used for a previous transaction and must be unique. |
| 422 Unprocessable Entity | INSUFFICIENT_FUNDS | The user's wallet balance is too low to complete the requested debit transaction. |
| 503 Service Unavailable | FX_RATE_UNAVAILABLE | The service was temporarily unable to retrieve a currency conversion rate. This is often safe to retry. |
| 500 Internal Server Error | INTERNAL_SERVER_ERROR | An unexpected error occurred on our end. Our team has been notified. This should be reported if it persists. |
Payout Specific Errors
These errors are specific to the Fiat Payouts service.
| HTTP Status | Error Code | Description |
|---|---|---|
| 403 Forbidden | CURRENCY_NOT_ENABLED | The specified currency is not enabled for payouts on the user's account. |
| 404 Not Found | PAYOUT_PROVIDER_NOT_FOUND | No payment provider could be found to process a payout for the specified currency and destination. |
| 422 Unprocessable Entity | DEBIT_CURRENCY_NOT_SUPPORTED | The combination of debitCurrency and currency is not allowed (e.g., debiting NGN for a non-NGN payout). |
| 422 Unprocessable Entity | MOMO_CODE_REQUIRED | A payoutMethod.code (operator code) is required for Mobile Money (MoMo) payouts in this region. |
Updated 20 days ago