rate_limited error

rate_limited is returned with HTTP 429. Retryable: yes. Nothing is charged for this error.

What it means

Too many requests for this API key.

Most likely cause

The key sent more requests than its bucket allows in the current window, usually from a loop or a batch job that does not pause.

How to fix it

Wait the number of seconds in the Retry-After header, then retry. Spread requests out to stay under the X-RateLimit-Limit value.

Example

Sending twice the per-key limit of 200 requests in one burst shows a count of HTTP 429 answers. Each one carries a Retry-After header.

for i in $(seq 1 400); do curl -s -o /dev/null -w "%{http_code}\n" https://YOUR_API_HOST/v1/account -H "Authorization: Bearer $LOOKVALID_API_KEY"; done | sort | uniq -c

An error response is one JSON envelope. Branch on code, never on the message text. The message and fix of a real response can be more specific than the defaults shown here.

1{
2  "error": {
3    "code": "rate_limited",
4    "message": "Too many requests for this API key.",
5    "fix": "Wait the number of seconds in the Retry-After header, then retry. Spread requests out to stay under the X-RateLimit-Limit value.",
6    "docs_url": "https://lookvalid.com/docs/errors/rate_limited",
7    "retryable": true,
8    "request_id": "req_3fK9pQ2xVb7LmN4sTz8WcA"
9  }
10}

See also

• All error codes with the response envelope.
• Rate limits.
• Quote the request_id when you write to hello@lookvalid.com.