Errors & rate limits
Error envelope
Section titled “Error envelope”Every error uses the same shape:
{ "error": { "code": "NOT_FOUND", "message": "Site site_123 not found" }}code is stable and machine-readable; message is human-readable and
may change.
Error codes
Section titled “Error codes”| Code | HTTP status | Meaning |
|---|---|---|
MISSING_TOKEN |
401 | No Authorization: Bearer … header. |
MALFORMED_TOKEN |
401 | Token doesn’t look like a tac_mcp_… token. |
TOKEN_NOT_FOUND |
401 | Token doesn’t match any known credential. |
TOKEN_REVOKED |
401 | Token was revoked in Settings → Connections. |
TOKEN_EXPIRED |
401 | Token expiry has passed. |
TOKEN_CREATOR_REMOVED |
401 | The person who created the token is no longer a member of the workspace. |
INSUFFICIENT_SCOPE |
403 | Token lacks the read scope. |
SITE_SCOPE_MISMATCH |
403 | Site-locked token referenced a different site. |
INVALID_INPUT |
400 | A query parameter failed validation (the message says which). |
NOT_FOUND |
404 | Unknown endpoint, or the resource doesn’t exist in your account. |
METHOD_NOT_ALLOWED |
405 | Only GET is supported. |
RATE_LIMITED |
429 | Per-token request budget exhausted. |
INTERNAL_ERROR |
500 | Something went wrong on our side. |
Rate limits
Section titled “Rate limits”Each token may make 120 requests per minute. When the budget is
exhausted the API returns 429 with a Retry-After header (seconds):
HTTP/1.1 429 Too Many RequestsRetry-After: 34
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please try again later." } }Back off until Retry-After elapses. The window is fixed (per
minute), so a sleep of at most 60 seconds always resets the budget.
For CI gates, one request per pipeline run
(GET /sites/:siteId/issues?impact=critical&limit=1) sits far below
the budget.