Development
Error Codes
Common JGME Pay API error codes, meanings, and recommended fixes for collection and disbursement flows.
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.