> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payfonte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Common Payfonte API error codes, meanings, and recommended fixes for collection and disbursement flows.

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

```json theme={null}
{
  "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

<Steps>
  <Step title="Check HTTP status and errorCode">
    Parse both values first to classify auth, validation, configuration, or processing issues.
  </Step>

  <Step title="Verify request basics">
    Confirm `client-id`, `client-secret`, provider slug, reference uniqueness, and integer minor-unit `amount`.
  </Step>

  <Step title="Check dashboard state">
    Confirm wallet status, integration status, disbursement PIN, webhook config, and whitelisted IP settings.
  </Step>

  <Step title="Retry safely">
    Use idempotent retries with exponential backoff for transient failures.
  </Step>
</Steps>

## Related Docs

<CardGroup cols={3}>
  <Card title="Endpoint Specification" icon="diagram-project" href="/en/guides/introductions/endpoint-specification">
    Response format, filtering, and API conventions.
  </Card>

  <Card title="Supported Providers" icon="globe-africa" href="/en/guides/introductions/supported-providers">
    Validate provider slugs and market coverage.
  </Card>

  <Card title="Testing" icon="flask" href="/en/guides/introductions/testing">
    Reproduce and validate error scenarios in sandbox.
  </Card>
</CardGroup>