Errors & limits

Errors are standard HTTP status codes with a JSON detail message. Limits are per IP while the service is free.

Error format

json

{ "detail": "Document exceeds the 25 MB limit." }

Parameter	Type	Description
400	Bad request	Invalid input — empty document, malformed JSON/base64/id, or a URL the SSRF guard refused (non-public host).
401	Unauthorized	An Authorization header was presented but the API key is invalid or disabled. Anonymous calls (no header) are never 401.
404	Not found	No warrant or fact-check exists for that id.
413	Too large	The document (or fetched URL body) exceeds the 25 MB cap.
422	Validation	The request body does not match the schema (e.g. an unknown feedback verdict).
429	Rate limited	Too many requests — honour the Retry-After header.
501	Not implemented	URL intake on /v1/warrants — send file or bytes_b64, or use the MCP verify_document tool, which accepts a url.
502	Fetch failed	A {"url": ...} document could not be fetched from its host.

Anonymous: 20 documents/day per IP. With a free API key: 50/day on your own quota. Both sit behind a short-window burst guard of ~10 requests.
429 responses include Retry-After — back off and respect it.
Hosted agents note: anonymous callers behind one egress IP share a budget — get a key and the quota is yours alone.

25 MB max document size — uploads and URL fetches alike.
Inputs: PDF, or images (.png .jpg .jpeg .webp .bmp .tif) for forensics; PDF/text/HTML for the analysis tools.
URL intake fetches public http(s) hosts only; redirects are re-validated hop by hop.

Don't retry 400, 413, or 501 — they won't change.
On 429, wait Retry-After seconds.
On a streamed error event or 5xx, back off exponentially — failures are usually transient.
Use ?stream=1 for deep fact-checks and image forensics rather than holding a blocking request open.
Cache-check first (GET /v1/warrants/check) — identical bytes are already deduplicated by content hash.