Errors and recovery¶
Check HTTP status, JSON-RPC errors and tool-level errors separately. HTTP 200 by itself is not evidence that a read succeeded.
HTTP and protocol errors¶
| Status | Typical meaning | Action |
|---|---|---|
| 400 | Invalid JSON-RPC or unsupported protocol-version header | Correct the request; do not retry unchanged |
| 401 | Missing, invalid, expired or revoked credential; lost account/fleet eligibility | Stop; verify credentials and current authorization |
| 403 | Browser Origin is not allowed | Use your authorized backend integration |
| 404 | Unsupported JSON-RPC method | Use the supported MCP methods |
| 405 | Non-POST request | Use HTTP POST |
| 413 | Request body exceeds 65,536 bytes | Reduce the request |
| 415 | Content-Type is not application/json | Send JSON with the correct header |
| 503 | Authentication lookup unavailable | Retry later with a bounded delay |
Authentication failures can have an empty body. Do not assume every HTTP error is JSON. Any proxy-generated 429 or 5xx response also needs bounded backoff; respect a valid, capped Retry-After when present. This release does not advertise per-key rate-limit headers or a contractual throughput allowance.
Tool-level errors¶
Validation errors, unknown arguments, unavailable snapshots and read failures can return HTTP 200 with:
{
"jsonrpc": "2.0",
"id": 42,
"result": {
"content": [{"type": "text", "text": "Invalid snapshot cursor for this query."}],
"isError": true
}
}
Do not treat a failed call as an empty dataset. Current tool errors have human-readable messages, not stable machine error codes; do not build permanent business logic around exact wording.
Recovery rules¶
- Expired snapshot: restart the complete bounded read. Keep any downstream duplicate-prevention state; the new read may contain previously seen rows.
- Snapshot too large: split the date range, down to a day if needed. Never accept a silently truncated export.
- Snapshot quota: continue an existing cursor or wait for expiry. Creating a fresh snapshot on every page is incorrect.
- Timeout: retry the same snapshot cursor a bounded number of times. If it expires, restart and reconcile explicitly.
- Invalid cursor: check filters, limit, pagination mode and credential context. Do not modify the cursor.
- Read failed: retain the last successful state, alert the operator and retry later; do not erase downstream records.
Logs should contain your own request correlation ID, tool name, status and attempt count. Never log the Authorization header, raw fleet payload or private key.