Error Handling

The API uses conventional HTTP response codes. Error bodies come in three shapes depending on which layer rejects the request.

Error response shapes

Standard errors (validation failures, missing resources, state conflicts, server errors) return a flat body with a machine-readable code and a correlationId you can quote to support. Some codes also include a details object (for example, field-level validation errors):

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "correlationId": "01JZWX3F9G2K4M6P8R0T2V4X6Y",
  "details": { "organization_id": "Invalid uuid" }
}

Authentication and permission errors from the API-key layer (401, and 403 when the key lacks a scope) use a simpler two-field body with no code:

{
  "error": "API key required",
  "message": "Please provide an API key in the X-API-Key header"
}

Rate-limit errors (429) include retryAfter in the body and a Retry-After header:

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Maximum 100 requests per 60 seconds",
  "code": "RATE_LIMIT_EXCEEDED",
  "statusCode": 429,
  "retryAfter": 1800
}

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.
`409`	Conflict - Resource is in the wrong state for the request (for example scheduling a project that is not ready, requesting survey results for a broadcast project, or retrying an idempotent write that is still processing).
`422`	Unprocessable - The request was understood but can’t be executed (for example reusing an `Idempotency-Key` with a different body, or scheduling with insufficient balance).
`429`	Too Many Requests - Rate limit exceeded. See Rate Limits.
`500`	Internal Server Error - Something went wrong on our end.

Common error codes

Code	Description
`VALIDATION_ERROR`	Request parameters or body failed validation. Field-level messages are in `details`.
`ORG_ACCESS_DENIED`	Requested organization is not in your accessible hierarchy.
`RATE_LIMIT_EXCEEDED`	Too many requests - wait for the `Retry-After` seconds before retrying.
`INVALID_STATE_TRANSITION`	Project is not in a state that allows this operation.
`NOT_A_SURVEY`	The endpoint only applies to survey projects (`type: survey`).
`LIST_NOT_READY`	Contact list must finish importing before it can be analyzed.
`INSUFFICIENT_BALANCE`	Wallet balance cannot cover the scheduled send. `details` includes the shortfall.
`IDEMPOTENCY_CONFLICT`	The same `Idempotency-Key` is still processing - retry after the `Retry-After` seconds.
`IDEMPOTENCY_MISMATCH`	An `Idempotency-Key` was reused with a different request body - that’s a client bug; use a fresh key for new requests.
`DATE_RANGE_TOO_LARGE`	Date range exceeds the maximum allowed (31 days).
`DATE_TOO_OLD`	Start date exceeds the look-back limit: 180 days for `/messages/stats` and `/ledger/*`, 90 days for `/projects/stats`.
`FUTURE_DATE_NOT_ALLOWED`	Date range may not end in the future.
`INVALID_DATE_FORMAT`	Date parameter must be in `YYYY-MM-DD` format.

Note that 401 responses and permission-scope 403 responses come from the authentication layer and carry no code field (see the shapes above).

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 (16-200 printable ASCII characters; a UUID is recommended) on every write request. Retried calls with the same key within 24 hours return the cached response from the first call, marked with an X-Idempotent-Replayed: true response header. Reusing a key with a different body returns 422 (IDEMPOTENCY_MISMATCH).

How agents should recover

Unattended integrations and AI agents should encode this recovery matrix rather than treating all failures alike:

Status	Retry?	Recovery action
`400`	Never	Fix the request parameters. Check `code` for specifics.
`401`	Never	Credential is missing or revoked. Escalate to a human operator; keys are created in the dashboard, not over the API.
`403`	Never	Stay inside the key’s organization hierarchy or request a key with the right scope.
`404`	Never	Verify the resource ID against a fresh list call.
`429`	After waiting	Sleep for the `Retry-After` seconds. Never retry tighter than once per second.
`500`-`504`	With backoff	Exponential backoff with jitter: 1 second base, double each attempt, 60 second cap, give up after 5 attempts.

Before treating repeated 5xx failures as your bug, check status.politicalcomms.com. A standalone machine-readable version of this playbook is published at politicalcomms.com/errors.md.

Reporting bugs

If you see a 500 response or a code that’s not documented here, please email support@politicalcomms.com with:

Your request method and path
The full response body, including the correlationId field (we use it to look up server-side logs; it is also sent as the X-Correlation-ID response header)
Approximate timestamp (UTC is easiest)

Introduction

Webhooks

Endpoints

Error response shapes

HTTP status codes

Common error codes

Retrying safely

How agents should recover

Reporting bugs

​Error response shapes

​HTTP status codes

​Common error codes

​Retrying safely

​How agents should recover

​Reporting bugs

Error response shapes

HTTP status codes

Common error codes

Retrying safely

How agents should recover

Reporting bugs