errorCode in your handling logic.
Collection Errors
| Status | Error Code | Meaning | Recommended Action |
|---|---|---|---|
404 | CurrencyExchangeValueNotFound | Exchange value needed for currency conversion is unavailable. | Retry later or use a supported currency/country pair. |
Disbursement Errors
| Status | Error Code | Meaning | Recommended Action |
|---|---|---|---|
404 | TransferRecipientNotFound | Transfer recipient does not exist (or was removed). | Re-validate and recreate recipient, then retry. |
500 | InActiveWallet | disbursement wallet is inactive or on post-no-debit (PND). | Check wallet status on dashboard before retrying. |
500 | InsufficientBalance | Wallet balance is too low for disbursement. | Fund disbursement wallet and retry. |
500 | InvalidDisbursementConfiguration | Disbursement setup is incomplete or invalid. | Review disbursement settings in dashboard. |
400 | InvalidDisbursementPin | Disbursement PIN missing or incorrect. | Set/reset PIN and retry with valid value. |
403 | InvalidDisbursementWhitelistedIP | Request IP is not whitelisted for disbursement. | Add caller IP to allowlist or route from approved IP. |
409 | TransferRecipientExists | Recipient already exists. | Reuse existing recipient instead of creating a new one. |
400 | TransferRecipientBlacklisted | Recipient is blacklisted. | Use another eligible recipient. |
422 | ValidateAuthorizationURLError | Authorization URL validation failed for disbursement flow. | Check authorization endpoint availability and response behavior. |
400 | RecipientDailyLimitReached | Recipient daily limit has been exceeded. | Retry later or lower amount if supported. |
400 | DuplicateDisbursementDetected | Same amount to same recipient detected in short window. | Use unique references and idempotent retry strategy. |
General Errors
| Status | Error Code | Meaning | Recommended Action |
|---|---|---|---|
409 | DuplicateTransactionReference | A request used a previously used reference value. | Generate unique references per transaction. |
422 | ValidationError | One or more request fields are invalid. | Fix field types/values and retry. |
404 | IntegrationNotFound | Requested provider integration is not configured/active. | Activate integration in dashboard. |
404 | ResourceNotFound | Requested resource does not exist. | Verify endpoint path and identifiers. |
500 | InvalidProvider | Unsupported provider slug passed in request. | Use a valid slug from Supported Providers. |
500 | InternalServerError | Unexpected server-side failure. | Retry with backoff and contact support if persistent. |
Fast Troubleshooting Flow
Check HTTP status and errorCode
Parse both values first to classify auth, validation, configuration, or processing issues.
Verify request basics
Confirm
client-id, client-secret, provider slug, reference uniqueness, and integer minor-unit amount.Check dashboard state
Confirm wallet status, integration status, disbursement PIN, webhook config, and whitelisted IP settings.
Related Docs
Endpoint Specification
Response format, filtering, and API conventions.
Supported Providers
Validate provider slugs and market coverage.
Testing
Reproduce and validate error scenarios in sandbox.