# Political Comms API: Error Recovery Playbook

How agents and services should handle every failure mode of the Political Comms REST API (`https://api.politicalcomms.com/v1`). Full error code catalog: https://docs.politicalcomms.com/api-reference/errors. Authentication walkthrough: https://politicalcomms.com/auth.md

## Error response shape

Every error returns structured JSON:

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

Parse `code` for programmatic handling and `statusCode` for retry decisions. A `X-Request-ID` response header, when present, identifies the request in server-side logs; include it in support reports.

## Recovery by status code

| Status | Retry? | Recovery action |
| --- | --- | --- |
| `400` | Never | The request is malformed. Fix parameters before sending again. Check `code` for specifics such as `INVALID_DATE_FORMAT`, `RANGE_TOO_LARGE` (max 31 days), or `RANGE_TOO_OLD` (max 90 days back). |
| `401` | Never | The key is missing, malformed, or revoked (`INVALID_API_KEY`). Do not retry with the same credential. Surface the failure to a human operator; key creation happens in the dashboard, not over the API. |
| `403` | Never | The key is valid but lacks access (`ORG_ACCESS_DENIED`, `PERMISSION_DENIED`). Request data within the key's organization hierarchy or ask an operator for a key with the right scope. |
| `404` | Never | The resource does not exist. Verify the ID against a fresh list call before assuming a bug. |
| `429` | Yes, after waiting | Rate limit exhausted (`RATE_LIMIT_EXCEEDED`; per key over a 60-second sliding window: 100 requests/minute for reads, 60/minute for writes, 30/minute for deletes). Read the `X-RateLimit-Reset` header (Unix seconds) and sleep until that timestamp. Never retry tighter than once per second. |
| `500` `502` `503` `504` | Yes, with backoff | Transient server errors. Retry with exponential backoff and jitter: start at 1 second, double each attempt, cap at 60 seconds, give up after 5 attempts. Check https://status.politicalcomms.com before treating repeated failures as your bug. |

## Rate limit awareness

Every response carries rate-limit state. Track it instead of waiting for a `429`:

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1640995200
```

Start backing off when `X-RateLimit-Remaining` drops below 10. Cache hierarchy data for 5 to 10 minutes and completed-range stats indefinitely to stay under the limit. Elevated limits are available for production integrations: support@politicalcomms.com

## Safe retries and idempotency

- All `GET` endpoints have no side effects and are always safe to retry.
- For `POST` and `PATCH`, retry only on `429`, `500`, `502`, `503`, and `504`.
- Send a unique `Idempotency-Key` header on every write. A retried call with the same key returns the cached response from the first call, so retries cannot double-apply.

## Webhook failures

- Deliveries are signed with HMAC-SHA256 in the `X-Webhook-Signature` header (`sha256=...`). Validate the signature before processing; reject payloads that fail validation. Guide: https://docs.politicalcomms.com/api-reference/webhooks/signature-validation
- If your endpoint does not return `2xx` within 10 seconds, the platform retries on an exponential schedule: immediately, then 4, 16, and 64 seconds after each failure. After 4 failed attempts the delivery is marked failed and can be retried manually from the dashboard.
- Deduplicate on `event_id`: under network failure conditions the same event can arrive twice. Return `200` fast and process asynchronously.
- Retry policy reference: https://docs.politicalcomms.com/api-reference/webhooks/retry-policy

## When recovery fails

- Platform status and incident history: https://status.politicalcomms.com
- Undocumented `code` values or persistent `500`s: email support@politicalcomms.com with the method, path, full response body, `X-Request-ID`, and a UTC timestamp.
- Credential problems require a human operator: https://app.politicalcomms.com/ under Admin, then API Keys.

## Related

- OpenAPI 3.1 specification: https://politicalcomms.com/openapi.json
- Authentication walkthrough: https://politicalcomms.com/auth.md
- API overview: https://politicalcomms.com/api.md
- Site index for agents: https://politicalcomms.com/llms.txt