Errors and limits

Hanto returns JSON error bodies for failed API requests. A 404 no-match response is a completed lookup result, not a transport failure.

Response outcomes

HTTP status	Body	Meaning
`400`	`{"error":"invalid_request"}`	The JSON body is malformed or unsupported fields were sent.
`400`	`{"error":"invalid_email"}`	The `email` field is missing, empty, malformed, or unusable.
`400`	`{"error":"unsupported_email"}`	The submitted email is outside the current API scope.
`401`	`{"error":"unauthorized"}`	The bearer key is missing, invalid, or revoked.
`402`	`{"error":"insufficient_credits"}`	The workspace cannot accept another lookup at this time.
`404`	`{"lookup_id":"lookup_...","status":"not_found"}`	Hanto completed the lookup and could not return a match.
`429`	`{"error":"rate_limited"}`	The workspace exceeded the public API burst limit.
`502`	`{"error":"lookup_error"}`	Hanto could not complete resolver work for this request.
`503`	`{"error":"rate_limit_unavailable"}`	Hanto could not verify the rate-limit state, so the request was not executed.
`5xx`	`{"error":"server_error"}`	Hanto encountered a temporary service failure.

The public API allows up to 500 requests per minute per workspace. When the API returns 429, use the response headers to decide when to retry:

Header	Meaning
`RateLimit-Limit`	Maximum requests in the current window.
`RateLimit-Remaining`	Remaining requests in the current window.
`RateLimit-Reset`	Time when the current window resets.
`Retry-After`	Minimum time to wait before retrying.