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

# Error Codes

> Ran into an error? Don't worry—we've got you covered. This page lists all known error codes along with simple explanations and fixes to get you back on track.

The meCash API uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with meCash’s servers.

## meCash API Response Codes

### Success (2xx)

<CardGroup cols={1}>
  <Card title="200 OK" icon="check-circle" color="green">
    The request was processed successfully. Always examine the response data object to determine the specific outcome (e.g., successful or failed transaction).
  </Card>

  <Card title="201 Created" icon="plus-circle" color="green">
    A new resource was created successfully through your request. This typically occurs when creating new entities like Payouts or Virtual Accounts.
  </Card>
</CardGroup>

### Client Errors (4xx)

<CardGroup cols={1}>
  <Card title="400 Bad Request" icon="circle-exclamation" color="orange">
    The request failed due to invalid or missing required parameters. Double-check your JSON payload format and required fields.
  </Card>

  <Card title="401 Unauthorized" icon="key" color="orange">
    Authentication failed. This could be caused by an invalid or missing `x-api-key` in the header. Ensure you are using the correct key for the environment (Sandbox/Production).
  </Card>

  <Card title="403 Forbidden" icon="shield-xmark" color="orange">
    The API key doesn't have permissions or the IP is not whitelisted. Check **Developers → IP Whitelisting** in your dashboard.
  </Card>

  <Card title="404 Not Found" icon="magnifying-glass" color="orange">
    The requested resource does not exist. Verify the endpoint URL or the ID of the resource you are trying to access.
  </Card>

  <Card title="422 Unprocessable Entity" icon="file-circle-exclamation" color="orange">
    The request was well-formed but could not be followed due to semantic errors (e.g., an expired Quote ID or invalid recipient details).
  </Card>

  <Card title="429 Too Many Requests" icon="clock-rotate-left" color="orange">
    The API received too many requests in a short period. Implement exponential backoff for your retries.
  </Card>
</CardGroup>

### Server Error (5xx)

<CardGroup cols={1}>
  <Card title="500, 502, 503, 504" icon="server" color="red">
    These codes indicate errors on meCash’s servers. While uncommon, please report any instances to [support@me-cash.com](mailto:support@me-cash.com).
  </Card>
</CardGroup>

***

## Error Handling Strategies

### General Error Handling

<Steps>
  <Step title="Check the status field" icon="eye">
    All meCash responses contain a top-level `status` field. If it is `error`, check the `errorCode` for the specific cause.
  </Step>

  <Step title="Rely on Webhooks" icon="webhook">
    For asynchronous operations like Payouts, the initial API response might be `200 OK` (PENDING), but the final outcome is communicated via webhooks.
  </Step>

  <Step title="Use Idempotency" icon="repeat">
    When retrying requests (especially after network failures), use unique reference numbers to prevent duplicate transactions.
  </Step>
</Steps>

***

## Specific Error Types

When the API returns an error, the `errorCode` field provides specific context.

<AccordionGroup>
  <Accordion title="INSUFFICIENT_BALANCE" icon="wallet">
    **Description**: Your wallet does not have enough funds to complete the transaction.
    **Fix**: Fund your wallet via the dashboard or a mobile money collection before retrying.
  </Accordion>

  <Accordion title="INVALID_QUOTE" icon="calculator">
    **Description**: The `quoteId` provided is invalid, expired, or has already been used.
    **Fix**: Quotes typically expire after a few minutes. Generate a new quote and use the fresh `quoteId`.
  </Accordion>

  <Accordion title="INVALID_PARAMETER" icon="code">
    **Description**: One or more parameters in the request body are missing or malformed.
    **Fix**: Refer to the endpoint's request body schema and verify all required fields.
  </Accordion>

  <Accordion title="DUPLICATE_REFERENCE" icon="copy">
    **Description**: A transaction with the same reference number already exists.
    **Fix**: Ensure each transaction has a unique reference, or if retrying a failure, verify if the first attempt succeeded.
  </Accordion>

  <Accordion title="ACCOUNT_LOOKUP_FAILED" icon="user-slash">
    **Description**: We could not verify the recipient's bank account details.
    **Fix**: Double-check the account number and bank code. Use the [Account Enquiry](/miscellaneous/perform-account-enquiry) endpoint to verify details beforehand.
  </Accordion>

  <Accordion title="UNSUPPORTED_CURRENCY" icon="money-bill-transfer">
    **Description**: The specified currency is not supported for this operation or corridor.
    **Fix**: Check our [Supported Currencies](/quote-docs/supported-curriencies) guide for the available routes.
  </Accordion>
</AccordionGroup>