Errors
The error codes the API returns, what each means, and whether to retry.
Errors are JSON with a stable error code and a message for people:
{ "error": "invalid_ip", "message": "Expected one IPv4 or IPv6 address, not a CIDR range. No request was counted." }Branch on error, not on message; messages may be reworded. A refused request never counts against your monthly
quota.
Error codes
| Error | What happened | What to do |
|---|---|---|
400 invalid_cursor | The cursor was not issued for this query. | Send the same query the cursor came from, or start without one. |
401 unauthorized | The API key is missing, mistyped, revoked or expired, or was sent in the URL. | Check the Authorization header. See Authentication. |
402 quota_exceeded | The workspace has used its monthly quota. | Wait for the quota to reset at the start of the next month. See Rate limits and quotas. |
402 project_cap_exceeded | The key's project has reached its own monthly cap. | Raise or remove the cap in the project's settings. |
410 cursor_expired | The data was updated since the cursor was issued. | Start again without a cursor. |
413 payload_too_large | The request body is over 1 MiB. Only POST /mcp takes a body. | Send a smaller request. |
422 invalid_ip | Not one IPv4 or IPv6 address, for example a CIDR range. | Send a single address. |
422 non_public_ip | A private, reserved or other special-purpose address, on a call that needs a public one. | lookup_ip answers these with is_bogon: true instead. |
422 invalid_domain | Not a hostname with at least two labels. | Send a name such as example.com, with no scheme or path. |
422 invalid_asn | Not an AS number from 1 to 4294967295. | Send 64500 or AS64500. |
429 rate_limited | Over your plan's requests per minute, or too many refused keys from your address. | Wait the Retry-After header's seconds, then retry. |
500 internal_error | Something failed on our side. | Retry once; if it persists, tell us. |
503 release_unavailable | No lookup data is loaded right now. | Retry later. |
503 service_unavailable | The API is briefly overloaded. | Wait the Retry-After seconds, then retry. |
Other shapes
A few responses come from the web framework rather than the API, and have a detail field instead of error:
422with{"detail": [...]}: a query parameter is out of range, for examplelimit=5000or acursorover 1024 characters.404with{"detail": "Not Found"}: no such path. Check for a typo.405with{"detail": "Method Not Allowed"}: every lookup is aGET.
Paths have no trailing slash. With one, the API redirects to the path without it, and most HTTP clients drop the
Authorization header when they follow that redirect, so the request ends in 401. Send the path as the reference
shows it.
The MCP server refuses calls from web pages other than the console with 403, and answers 405 to anything but
POST.
Retrying
Retry only 429, 500 and 503, and wait the Retry-After seconds when the header is there. Every other error will
come back the same until the request changes.
Request IDs
Every response except a 500 has an X-Request-ID header. Include it when you contact
support@ipalmanac.com about a request.