Errors
REST errors return JSON with a stable error code and, on most responses, a human-readable message. Branch on error, never on the message. New codes are additive.
A miss is not an error
When a page cannot be read at or above the 0.7 trust gate, the call returns 200 with product: null and the below-gate confidence. On an API key, a miss is never billed and never uses quota. An x402 call settles its payment before the read runs, so it is paid whatever the read returns.
REST
| HTTP | error | when |
|---|---|---|
| 400 | invalid_json | The request body is not valid JSON. |
| 401 | unauthorized | No Authorization header, or the lgk_ key is unknown or revoked. |
| 402 | quota_exceeded | A Free account has used its included trusted reads for this calendar month (UTC). |
| 402 | cost_fuse | A Free account has hit its usage safety limit. Add a plan to continue. |
| 402 | trial_used_up | A 30-day trial has used its reads, and the Free plan's reads for this month are used too. Nothing was charged. |
| 405 | method_not_allowed | Wrong HTTP method. The v1 tools accept POST only; the Allow header says which. |
| 422 | invalid_request | Wrong arguments, for example both url and gtin, neither, or not 2 to 5 URLs to compare. |
| 429 | rate_limited | Over your plan's per-minute budget. Wait for retry-after seconds. |
| 500 | insert_failed | report_outcome could not store the outcome. |
| 502 | upstream_unavailable | The extraction worker did not respond in time. Safe to retry. |
| 503 | external_worker_not_configured | The extraction worker is not configured. Should not happen in production. |
A 402 for quota also carries plan, used, included and upgrade_url. A 429 carries retry-after; see rate limits.
MCP
POST /api/mcp speaks JSON-RPC 2.0. A tools/call with no API key and no payment returns HTTP 402 with an x402 body, { x402Version, error, accepts }, and the same again with settle_error when a payment fails to settle. Bad tool arguments come back as a normal result with isError: true. Everything else is a JSON-RPC error:
| HTTP | code | when |
|---|---|---|
| 200 | -32700 | The request body is not valid JSON. |
| 200 | -32601 | Unknown JSON-RPC method. |
| 200 | -32602 | Unknown tool name in tools/call. |
| 402 | -32098 | Keyed call: monthly quota reached, the Free usage safety limit hit, or a 30-day trial and this month's Free reads are both used up (nothing was charged). |
| 429 | -32099 | Keyed call: over your plan's per-minute budget. |
| 405 | -32000 | GET instead of POST. |