Errors & limits
Transport-level failures use HTTP status codes; tool-level issues return a structured error object in the tool result instead of failing the call.
HTTP status codes
| Code | Meaning | Fix |
|---|---|---|
| 401 | Token missing or expired | Re-run the authorize flow (trigger any tool). |
| 402 | No active subscription | Subscribe or renew in Billing. |
| 403 | Missing required scope | Reconnect so the client requests docs:read. |
| 429 | Fair-use rate limit | Slow down; retry after a short pause. |
Tool-level results
| Error | Meaning |
|---|---|
payload_too_large | Result exceeds the response-size cap — narrow the query or paginate with cursor/limit. |
bad_request | Invalid or missing arguments for the tool. |
insufficient_credits | (AI chat) Snapital SnapCredits exhausted — top up your Snapital wallet. |
snapital_auth_failed | (AI chat) Invalid or unauthorized Snapital AI key. |
snapital_unavailable | (AI chat) The Snapital service is temporarily unreachable. |
Rate limits & sizes
- Requests are rate-limited per authenticated subject (fair use). A burst returns 429.
- Every tool result is capped in size; large result sets return
payload_too_large— use pagination. - List tools return a
nextCursor; pass it back to page through the full corpus.
Still stuck connecting? Re-check the Quickstart and Authentication pages.