> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and limits

> Handle Hanto API errors, no-match responses, and public rate 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.                                |

## Rate limit

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.     |

## Retry guidance

* Do not retry `400` or `401` responses until the request or key is corrected.
* Treat `404` as a final no-match result.
* Retry `429` after `Retry-After`.
* Retry `502`, `503`, and other `5xx` responses with backoff.