Docs · Errors

Errors

Every error uses the same JSON shape and a conventional HTTP status. Errors are never charged.

Error

{
  "request_id": "req_9f1c…",
  "status": "error",
  "credits": { "charged": 0, "balance": 999 },
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "One or more parameters are invalid.",
    "docs_url": "https://gridlode.com/docs/errors#invalid_parameter",
    "details": [ { "field": "domain", "message": "Value error, not a valid domain name" } ]
  }
}

Error codes

Code	HTTP	Meaning
`invalid_parameter`	400	A parameter is missing or invalid. details lists each field.
`invalid_json`	400	The POST body isn't a JSON object.
`forbidden_host / forbidden_port`	400	The URL points to a private address or a port we don't fetch.
`unsupported_content_type`	400	The URL returned something that isn't a web page (image, PDF…).
`tld_without_rdap / tld_without_whois`	400	The registry doesn't offer that protocol. Try the other one.
`missing_api_key / invalid_api_key`	401	No key, a malformed key, or a revoked key.
`insufficient_credits`	402	Your balance can't cover the call.
`spend_cap_reached`	402	Your monthly spend cap is reached.
`disallowed_by_robots_txt`	403	The site's robots.txt disallows the URL.
`account_suspended`	403	Contact [email protected].
`unknown_endpoint`	404	There is no engine at that path.
`rate_limited`	429	Too many requests. Respect Retry-After.
`target_http_403 / target_http_5xx`	424	The target site refused or failed.
`fetch_failed / rdap_error / dns_unavailable`	424	The upstream source didn't answer correctly.
`worker_unavailable / engine_disabled`	503	Temporary problem on our side. Retry with backoff.
`target_timeout / whois_timeout`	424	The target didn't answer in time.

Retrying

Errors from the target site use 424 Failed Dependency: the request was valid, but the site or registry we fetched from failed, refused or timed out. Retry 424, 429 and 503 with exponential backoff (for example 1 s, 2 s, 4 s, then give up). Don't retry 400, 401, 402 or 403 without changing the request.