API errors and rate limits

The status codes Forager returns, what each error body looks like, and the rate limits to plan for.

Authentication

Send your API key in the X-API-KEY header on every request. See Authentication. If authentication fails, the quickstart documents these responses:

Status	Message	Meaning
`403`	`Authentication credentials were not provided.`	The `X-API-KEY` header is missing or the key is not valid.
`403`	`Forbidden`	The key does not have permission to access the resource.

A missing or invalid key returns 403, not 401, with this body:

{"detail": "Authentication credentials were not provided."}

The feedback endpoints in the API reference document 403 for a missing or invalid key, a key for a different account, or an inactive API key user.

Status	Where documented	Meaning
`400`	Feedback endpoints	Validation failed: an invalid contact value (for example a phone number that cannot be parsed as E.164, or a malformed email), an unrecognised `contact_status`, or a missing required field.
`403`	Every endpoint	Authentication failed (see above).
`429`	Autocomplete and feedback endpoints	Rate limit exceeded (see below).

Other operations document only their success response and 403 in the API reference.

Endpoints	Limit	Response when exceeded
Autocomplete (all six)	10 requests per second per account	`429`
Feedback (all three)	60 requests per minute per account, shared across the three endpoints	`429`

The single work email lookup is rate limited for interactive use. For enrichment runs, use the bulk work email lookup.

Polling a work email lookup or batch never consumes credits. While a lookup job is not finished, a Retry-After header suggests when to poll again.
A bulk work email batch is rejected, and nothing is charged, if your credit balance cannot cover the whole batch.

See Credit pricing for credits per request.

Last modified on October 28, 2026