Skip to help content
AICD API
Read the code, fix the cause

Troubleshooting

Map common HTTP and MCP errors to a safe fix without sharing a secret.

Reviewed Sep 15, 2026Owner: AICD APISource: a6e8820Read as Markdown

Authentication and access

  • 401 unauthorized: the key is missing, malformed, unknown, revoked, expired, or belongs to an inactive account. Add the correct bearer key or replace it. Do not paste it into a support message.
  • 403 forbidden: the valid key does not have the required scope, or the account or workspace role cannot perform the action. Use a properly scoped key 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.
  • 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: the paid MCP flow is not open. Do not retry automatically.
  • 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. Paid MCP is closed, so wallet or payment errors in a draft setup are not a supported production flow.

Links