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

# Error Handling

> Understanding and handling API errors

## Success Responses

| Code  | Meaning                                |
| ----- | -------------------------------------- |
| `200` | Request succeeded                      |
| `201` | Resource created                       |
| `204` | Request succeeded, no content returned |

## Client Errors

| Code  | Meaning      | Action                                   |
| ----- | ------------ | ---------------------------------------- |
| `400` | Bad request  | Check request format and required fields |
| `401` | Unauthorized | Verify your API token                    |
| `403` | Forbidden    | Check permissions for this resource      |
| `404` | Not found    | Resource doesn't exist                   |
| `429` | Rate limited | Wait and retry with backoff              |

## Server Errors

| Code  | Meaning             | Action            |
| ----- | ------------------- | ----------------- |
| `500` | Internal error      | Retry the request |
| `502` | Bad gateway         | Retry the request |
| `503` | Service unavailable | Retry the request |

## Error Response Format

```json theme={null}
{
  "error": {
    "message": "Resource not found",
    "code": "NOT_FOUND",
    "status": 404
  }
}
```

## Retry Strategy

For 5xx errors and 429 errors:

<Steps>
  <Step title="First Retry">
    Wait 1 second, retry
  </Step>

  <Step title="Second Retry">
    Wait 2 seconds, retry
  </Step>

  <Step title="Third Retry">
    Wait 4 seconds, retry
  </Step>

  <Step title="Continue">
    Continue doubling up to 30 seconds max
  </Step>
</Steps>

## Example Error Handler

```javascript theme={null}
async function handleApiResponse(response) {
  if (response.ok) {
    return response.json();
  }

  const error = await response.json();

  switch (response.status) {
    case 400:
      throw new Error(`Bad request: ${error.error.message}`);
    case 401:
      throw new Error('Invalid API token');
    case 403:
      throw new Error('Permission denied');
    case 404:
      throw new Error('Resource not found');
    case 429:
      throw new Error('Rate limited - try again later');
    default:
      throw new Error(`API error: ${error.error.message}`);
  }
}
```