MCP server and AI apps
Limits and error codes
Timeouts, token lifetimes, rate limits and the error codes users relay from their AI app.
Limits and error codes
When a client pastes an error from their AI app, it is usually one of the codes below. Each comes with a fixed, safe explanation, so the app's wording should match.
Limits
| Limit | Value |
|---|---|
| Overall request budget | 45 seconds by default (configurable up to 120), including sign-in checks and any form shown to the user |
| Single API call | 15 seconds by default |
| Request body | 256 KB by default |
| Response size | 1 MB by default |
| MCP access token | 5 minutes, refreshed by the app |
| Exchanged API token | 60 seconds |
| Refresh grant on Test | Rotating, 90-day absolute lifetime |
| Identity checks | 300 per identity per minute; unlinked identities 5 per minute each and 30 per minute overall, one at a time |
| Token exchange | One start per second per server process, at most four waiting |
| Per-connection call rate | Set per environment |
Sign-in and identity codes
| Code | Message the user sees | Action |
|---|---|---|
invalid_token | Authentication required. | Reconnect with the email code. |
account_not_found | No HockeyStick account exists for the email. | Invite the user, or check they used the right email. |
identity_untrusted | Use the email code connection for HockeyStick. | Sign in again with the email code. |
identity_unverified | A verified email address is required. | Sign in again with the email code. |
identity_conflict | This HockeyStick account is linked to another identity. | Escalate to an admin to review the link. |
connection_disconnected | This AI connection was disconnected. Contact support to reconnect. | See Revoking and resetting AI access. |
insufficient_scope | The tool requires an additional permission. | Reconnect with hsai.write if they want changes. |
identity_rate_limited | Identity checks are rate limited. | Wait for the retry time. |
Platform and access codes
| Code | Meaning |
|---|---|
forbidden / FORBIDDEN | Not permitted, including "Staff permission required" for staff-only tools. |
ENGAGEMENT_FORBIDDEN | The engagement_id is not one this person can access. |
CONTEXT_REQUIRED | A staff write needs an explicit client. |
ACTIVATE_REQUIRED | The client does not have Activate. |
CLIENT_WRITE_REQUIRED | Staff tried to log revenue; only client users can. |
DELEGATED_ROUTE_FORBIDDEN | The call reached an API route outside the tool list. |
not_found | Missing or foreign record. |
invalid_arguments | The app sent bad input; the message names the field. |
exchange_rate_limited, input_rate_limited, rate_limited | Too many calls. Stop, wait, retry reads once at most. Never auto-retry writes. |
exchange_timeout | Authorisation timed out before anything ran. |
auth_unavailable, exchange_unavailable, admission_unavailable | The sign-in side is down or misconfigured. Escalate to engineering. |
Uncertain outcomes
These mean a write may have been saved: timeout, cancelled, api_unavailable, commit_unconfirmed, draft_commit_unconfirmed, admission_unconfirmed and the API's ..._OUTCOME_UNCONFIRMED and ..._COMMIT_UNCONFIRMED codes. Do not repeat. Read the record back, and pass the brief ID and request ID to engineering if it needs reconciling.
Brief-specific refusals are listed in Tool reference: briefs.