eewooksdevelopers
Release 0.2 documentationAPI 0.2.0 is live and verified. Check availability before integrating.

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.

Ewooks Developer Documentation · Updated 21 November 2026 · Synthetic examples only