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

# Error Handling

> Handle ChatAds API errors gracefully

## Error Response Format

All errors follow this structure:

```json theme={null}
{
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "meta": {
    "request_id": "d6a8f6f2-3b5a-4f0a-81ab-1b4a4c9dd5ea",
    "timestamp": "2026-03-08T21:56:33.877635522Z",
    "version": "1.0.0"
  }
}
```

## Error Codes

| Code                     | HTTP Status | Description                                                                                                           |
| ------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `MISSING_API_KEY`        | 401         | API key header missing                                                                                                |
| `INVALID_API_KEY`        | 401         | Invalid or revoked API key                                                                                            |
| `API_KEY_DISABLED`       | 403         | API key disabled                                                                                                      |
| `FORBIDDEN`              | 403         | Invalid API key type for this endpoint, API access not enabled for your team, or access denied                        |
| `INVALID_INPUT`          | 400         | Request body is missing or malformed                                                                                  |
| `PAYLOAD_TOO_LARGE`      | 413         | Request body exceeds the 1MB size cap                                                                                 |
| `MINUTE_LIMIT_EXCEEDED`  | 429         | Per-minute rate limit exceeded (includes `Retry-After: 60` header)                                                    |
| `DAILY_LIMIT_EXCEEDED`   | 429         | Daily request limit exceeded (includes `Retry-After: 3600` header)                                                    |
| `MONTHLY_LIMIT_EXCEEDED` | 429         | Monthly request limit exceeded (includes `Retry-After: 3600` header)                                                  |
| `IP_RATE_LIMITED`        | 429         | Too many failed auth attempts from this IP                                                                            |
| `INTERNAL_ERROR`         | 500         | Server error                                                                                                          |
| `REDIS_UNAVAILABLE`      | 503         | Rate limiter temporarily unavailable (free tier only — paid users are unaffected). Includes `Retry-After: 30` header. |

## Common Errors

### Missing API Key (401)

```json theme={null}
{
  "data": null,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required"
  },
  "meta": { "request_id": "...", "timestamp": "...", "version": "1.0.0" }
}
```

**Solution:** Add your API key to the `x-api-key` header.

### Invalid API Key (401)

```json theme={null}
{
  "data": null,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  },
  "meta": { "request_id": "...", "timestamp": "...", "version": "1.0.0" }
}
```

**Solution:** Check that your API key is correct and not revoked.

### Rate Limit Exceeded (429)

```json theme={null}
{
  "data": null,
  "error": {
    "code": "MINUTE_LIMIT_EXCEEDED",
    "message": "Per-minute rate limit exceeded. Retry after 60 seconds."
  },
  "meta": { "request_id": "...", "timestamp": "...", "version": "1.0.0" }
}
```

**Solution:** For all rate limit errors, check the `Retry-After` header and wait the indicated number of seconds before retrying. Alternatively, upgrade your plan to increase your limits.

## Handling Errors in Code

<CodeGroup>
  ```typescript TypeScript theme={null}
  try {
    const response = await client.analyzeMessage("...");

    if (response.error) {
      console.error(`Error: ${response.error.code}`);
      console.error(`Message: ${response.error.message}`);
      // Handle specific error codes
      if (response.error.code === 'MINUTE_LIMIT_EXCEEDED') {
        // Check Retry-After header and wait
      } else if (response.error.code === 'DAILY_LIMIT_EXCEEDED') {
        // Wait for daily reset
      }
    }
  } catch (error) {
    console.error('Network error:', error);
  }
  ```

  ```python Python theme={null}
  try:
      response = client.analyze_message(message="...")

      if response.error:
          print(f"Error: {response.error.code}")
          print(f"Message: {response.error.message}")
          # Handle specific error codes
          if response.error.code == 'MINUTE_LIMIT_EXCEEDED':
              # Check Retry-After header and wait
              pass
          elif response.error.code == 'DAILY_LIMIT_EXCEEDED':
              # Wait for daily reset
              pass
  except Exception as e:
      print(f"Network error: {e}")
  ```
</CodeGroup>

## Request IDs

Every response includes a `request_id` in the `meta` object. Include this ID when contacting support for faster issue resolution.