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

# Error Handling

> Handle API errors gracefully

Build robust integrations by handling errors properly.

## Error Response Format

All error responses follow a consistent structure:

```json theme={null}
{
  "message": {
    "code": 400,
    "error": ["Description of the error"]
  },
  "data": [],
  "type": "error"
}
```

| Field           | Type         | Description                          |
| --------------- | ------------ | ------------------------------------ |
| `message.code`  | integer      | HTTP status code                     |
| `message.error` | array        | List of error messages               |
| `data`          | array/object | Empty on error                       |
| `type`          | string       | Always `"error"` for failed requests |

## Handling Strategies

<AccordionGroup>
  <Accordion title="400 — Bad Request" icon="circle-xmark">
    **Cause:** Missing required fields or invalid parameter values.

    **Action:** Check your request body against the endpoint documentation. Validate all required fields before sending.

    ```json theme={null}
    {"message": {"code": 400, "error": ["The amount field is required"]}}
    ```
  </Accordion>

  <Accordion title="403 — Forbidden" icon="ban">
    **Cause:** Invalid, expired, or missing authentication token.

    **Action:** Request a new access token and retry. Ensure your API keys are correct.

    ```json theme={null}
    {"message": {"code": 403, "error": ["Requested with invalid token!"]}}
    ```
  </Accordion>

  <Accordion title="422 — Unprocessable Entity" icon="circle-exclamation">
    **Cause:** Valid request format but invalid business logic (e.g. cancelling a paid order).

    **Action:** Check the current state of the resource before attempting the action.

    ```json theme={null}
    {"message": {"code": 422, "error": ["Only pending orders can be cancelled"]}}
    ```
  </Accordion>

  <Accordion title="429 — Rate Limited" icon="clock">
    **Cause:** Too many requests in a short period.

    **Action:** Implement exponential backoff. Wait, then retry with increasing delays.

    ```php theme={null}
    $delay = min(pow(2, $attempt) * 100, 30000); // max 30s
    usleep($delay * 1000);
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  Never expose raw API error messages to end users. Map error codes to user-friendly messages in your application.
</Warning>