Errors & rate limits

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

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 → Integrations.
TOKEN_EXPIRED	401	Token expiry has passed.
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

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.