Skip to content

Errors & rate limits

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.

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.

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 Requests
Retry-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.