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

# Errors

> Understand the Leadsforge API error format and the error codes your integration should handle.

When a Leadsforge API request fails, the response carries an HTTP status and a JSON body that explains what went wrong. Branch on the `code` field: it is stable and machine-readable, while `message` is written for people and can change.

```json theme={null}
{
  "message": "invalid request body",
  "code": "bad_request",
  "data": {
    "validations": [
      "limit is a required field"
    ]
  }
}
```

`data` appears only on some errors. On validation errors it holds `validations`, with one message per invalid field.

## Error codes

| HTTP status | `code` | Meaning | What to do |
| - | - | - | - |
| 400 | `bad_request` | The body or a parameter is invalid. | Fix the request; do not retry it unchanged. |
| 401 | `missing_api_key` | The `Authorization` header is missing. | Send your API key. |
| 401 | `invalid_api_key` | The API key is unknown or was revoked. | Check the key, or create a new one. |
| 401 | `unauthorized` | Your account is blocked. | Contact support. |
| 402 | `insufficient_credits` | Your available credits, minus what is already reserved, do not cover the request, or a monthly free allowance is used up and your credits do not cover the next call. | Top up. For enrichment and other per-result operations, you can also ask for less (smaller limit or page). |
| 403 | `account_frozen` | Credit spending is paused for your account. | Contact support. |
| 404 | `not_found` | The job or resource does not exist in your account. | Check the ID. |
| 409 | `conflict` | The operation clashes with another one: an owner enrichment already running for the same maps search, a maps search that has not started yet, or a concurrent start with the same `Idempotency-Key`. | Retry later with the same request and key. |
| 409 | `idempotency_conflict` | A lookalike search with the same `Idempotency-Key` is still running. | Retry with the same key once it finishes. |
| 410 | `gone` | A search cursor expired or is invalid, or the search reached its maximum results. | Start a new search. |
| 429 | `rate_limited` | Too many requests, too many jobs running, or the service is temporarily busy. | Retry later; honor `Retry-After` when it is set. See [Rate limits](https://developer.salesforge.ai/leadsforge-api/concepts/rate-limits.md). |
| 500 | `internal` | Unexpected server error. | Retry with backoff; contact support if it persists. |
| 502 | `bad_gateway` | A temporary error. | Retry later. |
| 503 | `service_unavailable` | A synchronous email or phone lookup is not available for this channel, or a feature is temporarily unavailable. | For a synchronous lookup, start an asynchronous job instead; otherwise retry later. |

Each endpoint in the reference lists its endpoint-specific statuses and what they mean for that endpoint.

## Responses without a code

Two kinds of responses do not follow the format above:

* A request with a valid key to an unknown path or with the wrong method returns `404` with only a `message`. Without a valid key it gets `401` first.
* A request still running when the server timeout is reached is cut off with `503` and an empty body. The request may have completed on the server. Treat it like a network error: for job start requests, retry with the same `Idempotency-Key` so you do not start a second job.

## Credits on failed requests

A request that returns an error does not charge credits, and credits reserved for it are released. Two exceptions: a request cut off by the server timeout, and a job start that fails with a `5xx`. Either may already have started a job, which keeps running and is charged for the values it returns. Retry such a start with the same `Idempotency-Key`, or find the job by its `clientRequestID`, so you do not start it twice. See [Credits](https://developer.salesforge.ai/leadsforge-api/concepts/credits.md).

## Related resources

* [Rate limits](https://developer.salesforge.ai/leadsforge-api/concepts/rate-limits.md)
* [Credits](https://developer.salesforge.ai/leadsforge-api/concepts/credits.md)
* [Authentication](https://developer.salesforge.ai/authentication.md)


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