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

# Error Handling

> Conventional HTTP response codes with a structured error object containing code, message, and additional context.

The API uses conventional HTTP response codes. Error responses include a structured error object with `code`, `message`, and `statusCode` fields.

## Error response shape

```json theme={null}
{
  "success": false,
  "error": "The provided API key is invalid or has been revoked",
  "code": "INVALID_API_KEY",
  "statusCode": 401
}
```

## HTTP status codes

| Status | Meaning                                                                                     |
| ------ | ------------------------------------------------------------------------------------------- |
| `200`  | **Success** - Request completed successfully.                                               |
| `400`  | **Bad Request** - Invalid parameters or malformed request.                                  |
| `401`  | **Unauthorized** - Missing or invalid API key.                                              |
| `403`  | **Forbidden** - API key lacks required permissions or access denied.                        |
| `404`  | **Not Found** - Resource does not exist.                                                    |
| `429`  | **Too Many Requests** - Rate limit exceeded. See [Rate Limits](/api-reference/rate-limits). |
| `500`  | **Internal Server Error** - Something went wrong on our end.                                |

## Common error codes

| Code                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `INVALID_API_KEY`     | API key is missing, malformed, or revoked.                  |
| `ORG_ACCESS_DENIED`   | Requested organization is not in your accessible hierarchy. |
| `PERMISSION_DENIED`   | API key lacks required permission scope.                    |
| `RATE_LIMIT_EXCEEDED` | Too many requests - check the `X-RateLimit-Reset` header.   |
| `RANGE_TOO_LARGE`     | Date range exceeds the maximum allowed (31 days).           |
| `RANGE_TOO_OLD`       | Date range is too old (maximum 90 days).                    |
| `INVALID_DATE_FORMAT` | Date parameter must be in `YYYY-MM-DD` format.              |

## Retrying safely

* All `GET` endpoints are safe to retry - they have no side effects.
* For `POST` and `PATCH`, retry only on `429`, `500`, `502`, `503`, and `504` responses. Don't retry on `400`, `401`, `403`, or `404` - those indicate a problem with your request that won't be fixed by trying again.
* If you need stronger duplicate-write protection, send a unique `Idempotency-Key` header on every write request. Retried calls with the same key return the cached response from the first call.

## Reporting bugs

If you see a `500` response or a `code` that's not documented here, please email [support@politicalcomms.com](mailto:support@politicalcomms.com) with:

* Your request method and path
* The full response body
* Any `X-Request-ID` header in the response (we use this to look up server-side logs)
* Approximate timestamp (UTC is easiest)