Error Codes

All non-2xx responses include error details in this shape:

{
  "error": "Human-readable message",
  "errorCode": "MachineReadableCode"
}

Use both HTTP status and 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.

Retry safely

Use idempotent retries with exponential backoff for transient failures.

Endpoint Specification

Response format, filtering, and API conventions.

Supported Providers

Validate provider slugs and market coverage.

Testing

Reproduce and validate error scenarios in sandbox.

Getting Started

Core Concepts

Providers & Coverage

Development

Collect Payment

Disbursements

Collection Errors

Disbursement Errors

General Errors

Fast Troubleshooting Flow

Endpoint Specification

Supported Providers

Testing

​Collection Errors

​Disbursement Errors

​General Errors

​Fast Troubleshooting Flow

​Related Docs

Endpoint Specification

Supported Providers

Testing

Collection Errors

Disbursement Errors

General Errors

Fast Troubleshooting Flow

Related Docs