Troubleshooting

Authentication and access

• 401 unauthorized: the key is missing, malformed, unknown, revoked, or expired, or the credential or account is suspended. Add the correct bearer key or replace it. Do not paste it into a support message.
• 403 forbidden: the key is valid but the call is not allowed — a civic read or export call on an account without paid data access, a scope the key does not hold, or a workspace role that cannot perform the action. Use a properly scoped key, arrange paid access, or ask an owner or admin.
• 404 account_not_found: the workspace API account is not enabled. An owner or admin can try Account or contact support.
• 404 not_found on a snapshot: the snapshot does not exist, does not belong to this feed context, or expired. Create a new snapshot.

Limits and stale cursors

• 410 cursor_expired: create a fresh snapshot and restart from its boundary cursor.
• MCP tool error invalid_cursor: the cursor is malformed or belongs to a different query, filters, or limit. It is rejected before the search runs and before any payment. Start a new search without a cursor.
• MCP tool error read_failed: the civic read did not produce a chargeable result, including a cursor whose anchored record moved or vanished. No payment was settled. Start a new search without a cursor.
• 413 request_too_large: reduce the request body. A batch can contain at most 100 total IDs and the request body can be at most 64 KiB.
• 413 response_too_large: lower the page limit or request fewer records.
• 429 rate_limited: wait for the number of seconds in Retry-After, then retry once. Do not run a tight retry loop.

Availability and timeouts

• MCP tool error beta_unavailable: a civic call had no paid billing channel. Add a confirmed paid period, or do not retry. The report tools answer a missing paid access with their own error instead.
• 503 feed_unavailable: check source health and retry later with bounded backoff.
• MCP tool error service_unavailable: retry later with bounded backoff.
• 503 mcp_unavailable: reconnect once after a delay. If it continues, report the time and request ID if one was returned.
• 504 timeout: use a smaller data API query and retry later.
• MCP tool error timeout: use a smaller query and retry later. The MCP tool limit is 10 seconds.

No records found

1. Check the public coverage entry for the exact place and record subtype.
2. If the publisher is in the featured meeting-source list, check source status and the last successful check.
3. Remove optional filters and confirm dates and local timezone.
4. Open the government source link to see whether it published the record.
5. Report the missing record with the public source URL. Do not include a key.

Unsupported client or payment

A client is unsupported until AICD API publishes a completed ordinary-user test for it. The pay-as-you-go MCP channel is not enabled, so wallet and payment errors are not a supported flow.