---
title: "rate_limited error"
url: "https://lookvalid.com/docs/errors/rate_limited.md"
canonical_url: "https://lookvalid.com/docs/errors/rate_limited"
last_updated: "2026-10-22"
type: "reference"
summary: "HTTP 429 rate_limited: Too many requests for this API key. Cause, fix and a curl example."
related: ["https://lookvalid.com/docs/errors.md", "https://lookvalid.com/docs/rate-limits.md"]
---

# rate_limited error

HTTP 429 rate_limited: Too many requests for this API key. Cause, fix and a curl example.

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

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

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

## See also

- [All error codes](https://lookvalid.com/docs/errors.md) with the response envelope.
- [Rate limits](https://lookvalid.com/docs/rate-limits.md).
- Quote the `request_id` when you write to [hello@lookvalid.com](mailto:hello@lookvalid.com).

## Related

- [Errors](https://lookvalid.com/docs/errors.md)
- [Rate limits](https://lookvalid.com/docs/rate-limits.md)