Skip to main content

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.

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

​
Error response shape

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

​
HTTP status codes

StatusMeaning
200Success - Request completed successfully.
400Bad Request - Invalid parameters or malformed request.
401Unauthorized - Missing or invalid API key.
403Forbidden - API key lacks required permissions or access denied.
404Not Found - Resource does not exist.
429Too Many Requests - Rate limit exceeded. See Rate Limits.
500Internal Server Error - Something went wrong on our end.

​
Common error codes

CodeDescription
INVALID_API_KEYAPI key is missing, malformed, or revoked.
ORG_ACCESS_DENIEDRequested organization is not in your accessible hierarchy.
PERMISSION_DENIEDAPI key lacks required permission scope.
RATE_LIMIT_EXCEEDEDToo many requests - check the X-RateLimit-Reset header.
RANGE_TOO_LARGEDate range exceeds the maximum allowed (31 days).
RANGE_TOO_OLDDate range is too old (maximum 90 days).
INVALID_DATE_FORMATDate 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 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)