Standard status codes, a stable code in the body, and a plain next step for each.
{ "error": "quota_exhausted", "quota": 2000, "used": 2000 }The error field is the stable identifier to branch on. Some errors add fields: 402 carries the quota and what was used, 429 carries a reset time, 400 for a batch carries the maximum size.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | invalid_key | The key is missing, malformed, or revoked. | Check the Authorization header and the key on your account page. Revoked keys stop on the next request. |
| 402 | quota_exhausted | This month's lookups are spent. | Wait for the first of the month, or add a pack from the account page. The API never throttles silently. |
| 429 | rate_limited | Too many requests this minute for your plan. | Back off until the reset time in the body, then retry. |
| 404 | not_found | We do not hold that domain or technology. | Nothing to retry. The lookup is still spent for domain calls. |
| 400 | bad_domain | The domain is not a plausible hostname. | Send lower-case hostnames of 3 to 253 characters, letters, digits, dots and hyphens only. |
| 400 | bad_host | The hostname is not plausible. | Same rule as bad_domain. |
| 400 | bad_batch | The body is not {"domains": [...]} with 1 to 100 valid hostnames. | Send a JSON body with a domains array of at most 100 hostnames. |
| 503 | metering_unavailable | The quota could not be read, so nothing was served. | Retry in a moment. No lookup was spent. |