Errors
Errors are JSON with an error code. Paid requests that end in an error are refunded.
| Status | Body | When |
|---|---|---|
| 400 | {"error": "url_not_allowed"} | The URL is not public http(s): private, loopback, link-local and similar addresses are rejected, also after redirects. |
| 401 | {"error": "invalid_api_key"} | The key is unknown. |
| 402 | {"error": "insufficient_credits" | "keyless_limit", "message": "...", "checkout_url": "...", "pricing": {...}, "packs": [...], "action": {"type": "payment_link", "url": "https://api.contextfetch.dev/buy/instant", "prompt_to_user": "..."}} | Out of credits, or the keyless allowance is used up. Also sends X-Payment-URL. |
| 409 | {"error": "no_payment_method", "message": "..."} | Auto-reload requested for a key without a saved card. The message carries a buy link; buy with auto-reload on to save one. |
| 422 | - | Request validation failed, e.g. a query over 2,000 characters or a threshold outside 100 to 100,000. |
| 502 | {"error": "fetch_failed", "message": "..."} | The target page could not be fetched. |
| 503 | {"error": "recall_unavailable", "message": "..."} | Web search backends are down; retry shortly. |
| 432 | {"detail": {"error": "..."}} | /tavily/* only: out of credits (Tavily's own status), with the same X-Payment-URL header. Other /tavily/* errors also use this body shape. |