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

> ## Agent Instructions
> Forager is a REST API for B2B people, company and job post data: contact lookups (phone numbers, personal emails, work emails), person, company and job post search, and bulk data feeds.
> Server: https://api-v2.forager.ai. Send the API key in the X-API-KEY header. Most paths include {account_id}. Read FORAGER_API_KEY and FORAGER_ACCOUNT_ID from the environment; never put the key in client-side code, logs or prompts.
> To add Forager to a project, follow https://www.forager.ai/docs/guides/agent-quickstart.md. To pick an endpoint, read https://www.forager.ai/docs/guides/choose-an-endpoint.md. For end-to-end builds, see https://www.forager.ai/docs/recipes/overview.md.
> Most requests spend credits. Do not guess costs; use https://www.forager.ai/docs/api-overview/credit-pricing.md and ask the user before spending credits.
> Use only endpoints and fields defined in https://www.forager.ai/docs/openapi.yaml. Forager has no MCP server for the API yet; the /mcp endpoint on this site searches the documentation only.

# API errors and rate limits

> Authentication header, documented HTTP errors, rate limits for autocomplete and feedback endpoints, and what is still to be confirmed.

![API errors: 403 for authentication, 429 for rate limits and 400 for validation](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/api-errors-403-authentication.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=534483a1979052259ee30c946666ccbd)

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](https://www.forager.ai/docs/api-overview/authentication.md).

If authentication fails, the [quickstart](https://www.forager.ai/docs/api-overview/send-your-first-request.md) 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Authentication credentials were not provided."}
```

The feedback endpoints in the [API reference](https://www.forager.ai/docs/openapi/feedback) document `403` for a missing or invalid key, a key for a different account, or an inactive API key user.

## Documented status codes

| Status | Where documented | Meaning |
| - | - | - |
| `400` | [Feedback endpoints](https://www.forager.ai/docs/openapi/feedback) | 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.

## Rate limits

![API rate limits: a 429 response, then retries with growing backoff until the request succeeds](https://mintcdn.com/forager/EGsWCxLOYv1Cb__c/images/illustrations/api-rate-limits-429-retry-backoff.svg?fit=max\&auto=format\&n=EGsWCxLOYv1Cb__c\&q=85\&s=c528ba8506951191cd13ef137acaf5bd)

| Endpoints | Limit | Response when exceeded |
| - | - | - |
| [Autocomplete](https://www.forager.ai/docs/openapi/autocomplete) (all six) | 10 requests per second per account | `429` |
| [Feedback](https://www.forager.ai/docs/openapi/feedback) (all three) | 60 requests per minute per account, shared across the three endpoints | `429` |

The [single work email lookup](https://www.forager.ai/docs/openapi/work-emails/v2_datastorage_person_contacts_lookup_work_emails_create.md) is rate limited for interactive use. For enrichment runs, use the [bulk work email lookup](https://www.forager.ai/docs/openapi/work-emails/v2_datastorage_person_contacts_lookup_work_emails_bulk_create.md).

## Polling and credits

* 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](https://www.forager.ai/docs/api-overview/credit-pricing.md) for credits per request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.