Errors and rate limits

The Reporting API returns a stable error envelope:

{
  "error": {
    "code": "not_found",
    "message": "Team not found.",
    "request_id": "example-request-123"
  }
}

HTTP status	Meaning	Action
400	Invalid parameter, cursor, or date range	Correct the request before retrying
401	Missing, invalid, revoked or expired credential	Check the key or refresh/reconnect an OAuth client
403	Scope or plan does not allow the request	Review access and plan status
404	Resource missing or unavailable to this credential	Check the team and its allowlist; do not assume another tenant’s resource exists
429	Shared organisation or MCP request limit reached	Respect Retry-After and retry with backoff
500	Unexpected server failure	Retry cautiously and contact support if it persists
503	Temporary dependency failure	Retry with exponential backoff and jitter

Branch on the stable error.code or HTTP status, not the wording of message. Error details do not include internal exception traces.

Rate limits

API keys and OAuth clients share their organisation’s API quota. Read the returned RateLimit-* headers and Retry-After rather than hard-coding a quota. MCP results also contain rate_limit information, and the MCP service can apply additional request limits.

Avoid unbounded parallel requests. Use a bounded queue, respect backoff, and preserve pagination filters. A plan change or revoked access can change what a previously successful credential may do.

Request IDs and support

Responses include X-Request-Id. An integration can send a request ID containing 8-128 letters, numbers, dots, underscores, or hyphens; invalid values are replaced.

When contacting support, include the environment, endpoint, time in UTC, HTTP status, and request ID. Remove Authorization headers and customer report contents from logs and screenshots. Never send a usable key, refresh token, or session cookie.