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

# Error Handling

> Learn how to handle errors in DEXCHANGE-API

# Error Handling

## Overview

DEXCHANGE-API uses conventional HTTP response codes to indicate the success or failure of API requests. In general:

* Codes in the `2xx` range indicate success
* Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted)
* Codes in the `5xx` range indicate an error with our servers

## Error Response Format

All error responses follow this format:

```json theme={null}
{
  "success": false,
  "message": "Error description",
  "code": "ERROR_CODE"
}
```

## HTTP Status Codes

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 200  | Success - The request was successful             |
| 400  | Bad Request - The request was invalid            |
| 401  | Unauthorized - Invalid API key                   |
| 403  | Forbidden - You don't have permission            |
| 404  | Not Found - The requested resource doesn't exist |
| 429  | Too Many Requests - Rate limit exceeded          |
| 500  | Server Error - Something went wrong on our end   |

## Common Error Codes

### Authentication Errors

| Code              | Description                     |
| ----------------- | ------------------------------- |
| `INVALID_API_KEY` | The provided API key is invalid |
| `EXPIRED_API_KEY` | The API key has expired         |
| `MISSING_API_KEY` | No API key was provided         |

### Transaction Errors

| Code                    | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `INSUFFICIENT_FUNDS`    | The user doesn't have enough balance             |
| `INVALID_AMOUNT`        | The transaction amount is invalid                |
| `TRANSACTION_FAILED`    | The transaction could not be processed           |
| `DUPLICATE_TRANSACTION` | A transaction with this reference already exists |

### Validation Errors

| Code                     | Description                        |
| ------------------------ | ---------------------------------- |
| `INVALID_PHONE`          | The phone number format is invalid |
| `INVALID_CURRENCY`       | The currency is not supported      |
| `MISSING_REQUIRED_FIELD` | A required field is missing        |

### Service Errors

| Code                  | Description                                    |
| --------------------- | ---------------------------------------------- |
| `SERVICE_UNAVAILABLE` | The requested service is currently unavailable |
| `OPERATOR_ERROR`      | The mobile operator returned an error          |
| `TIMEOUT_ERROR`       | The request timed out                          |

## Best Practices

1. **Always check the response status**

   * Verify both HTTP status code and response body

2. **Implement proper error handling**

   * Handle both expected and unexpected errors
   * Log errors for debugging

3. **Retry mechanism**

   * Implement exponential backoff for 5xx errors
   * Don't retry on 4xx errors (except 429)

4. **Rate limiting**
   * Monitor rate limit headers
   * Implement rate limit handling

## Example Error Handling

```javascript theme={null}
try {
  const response = await dexchangeApi.initiatePayment({
    amount: 1000,
    phone: '221700000000',
  });
} catch (error) {
  if (error.code === 'INVALID_PHONE') {
    // Handle invalid phone number
  } else if (error.code === 'INSUFFICIENT_FUNDS') {
    // Handle insufficient funds
  } else {
    // Handle other errors
  }
}
```

## Support

If you encounter any errors that you can't resolve, please contact our support team:

* Email: [team@dexchange.sn](mailto:team@dexchange.sn)
* Status page: [status.dexchange.sn](https://status.dexchange.sn)