## Always check `success`

A `200` status does not always mean your request succeeded. Always read the `success` field of the response.

While your batch is still processing, `GET /v1/enrich/all/{request_id}` answers `200` with `"success": false` and the reason `Request not ready yet, try again in 30 seconds`. It answers the same way when the `request_id` is unknown, or when we have a temporary problem on our side.

Fetch your results within 30 days: after that, they may no longer be available.

**What to do:** wait 30 seconds and try again. To avoid polling, use a [webhook](https://developer.dropcontact.com/en/webhooks/), or add `forceResults=true` to get the records that are already enriched.

## Where to read the error message

Most errors look like this. The message is in `reason`:

```json
{
  "error": true,
  "reason": "Too many records, you can only submit up to 250 records",
  "success": false
}
```

Some errors (`404`, `422`, `500`, and errors from `GET /v1/account/credits`) put the message in `detail` instead:

```json
{
  "detail": "Not Found"
}
```

## Errors by status code

### 400 Bad Request

Your request is not valid. Returned by `POST /v1/enrich/all`.

| Message | What to do |
| --- | --- |
| `Missing data in JSON` | Send at least one record in `data`. |
| `Too many records, you can only submit up to 250 records` | Split your records into batches of 250 or less. |
| `Data size is too big, you can only submit up to 15 kB of data in a single record` | Make the record smaller. Large `custom_fields` are the usual cause. See [Input record](https://developer.dropcontact.com/en/reference/input-record/). |
| `Request contains invalid input` | Every record is in error. Read `data[].errors` for each record. |

### 401 Unauthorized

Your API key is missing or not valid. Returned by every endpoint.

| Message | What to do |
| --- | --- |
| `No api key received. Please set 'X-Access-Token' header with your api key as value.` or `no-credentials` | Add the `X-Access-Token` header to your request. See [Authentication](https://developer.dropcontact.com/en/authentication/). |
| `Unknown account` or `invalid-api-key` | Your API key is wrong or disabled. Check it in the [Dropcontact app](https://app.dropcontact.com/api). |

### 403 Forbidden

Your API key is valid, but the action is refused.

| Message | Endpoints | What to do |
| --- | --- | --- |
| `Sorry, you must contact the support to enable your API access!` | `POST /v1/enrich/all` | Contact support@dropcontact.com to enable API access. |
| `You submitted X valid items but only have Y credits left` | `POST /v1/enrich/all` | [Buy credits](https://app.dropcontact.com/pricing), or send fewer records. See [Credits Policy](https://developer.dropcontact.com/en/credits/). |
| `Unknown account` | All except `GET /v1/account/credits` | Your account is not set up for the API yet. Sign in once to the [Dropcontact app](https://app.dropcontact.com), then contact support if it keeps happening. |
| `This request id was not sent by you` | `GET /v1/enrich/all/{request_id}` | This `request_id` belongs to another account. Check that you use the right API key. |

### 404 Not Found

| Message | Endpoints | What to do |
| --- | --- | --- |
| `No webhook callback found` | `DELETE /v1/enrich/webhook` | There is no default webhook URL to delete. Nothing to do. See [Webhooks](https://developer.dropcontact.com/en/webhooks/). |
| `Not Found` | Any | The URL you called does not exist. Check it, for example `/v1/enrich/all` and not `/v1/all`. |

### 422 Validation Error

The request body or a parameter does not have the right format.

`detail` lists each field in error. Fix your request using the [API Reference](https://developer.dropcontact.com/en/reference/).

This is also the case when `custom_callback_url` or the default webhook URL is not a valid URL, or is longer than 2,083 characters. See [Webhooks](https://developer.dropcontact.com/en/webhooks/).

### 429 Too Many Requests

You sent too many requests in a short time (see [Rate limits](https://developer.dropcontact.com/en/rate-limits/)), or we have a temporary problem on our side. The message is `please retry in a few seconds`.

**What to do:** wait a few seconds and try again, leaving more time between each try.

### 500 Internal Server Error

Something went wrong on our side, and we are notified automatically. The message is `An error occurred. Please retry later.`

**What to do:** try again later. If it keeps happening, contact support@dropcontact.com.

### 502, 503, 504

These errors come from our network, in front of the API: maintenance or time limit exceeded.

**What to do:** try again later.

## Record errors and warnings

Some problems only affect one record. The request still succeeds, and the problem is listed under `data[].errors` or `data[].warnings` for that record.

| Key | Type | Meaning | What to do |
| --- | --- | --- | --- |
| `unexpected_field` | Error | Some fields are not recognized and are ignored. The record is still processed. | Fix the field names listed. See [Input record](https://developer.dropcontact.com/en/reference/input-record/). |
| `only_contact_data` | Error | The record has a person but no company identifier (company, website, company_linkedin, num_siren, siret), no email and no LinkedIn profile of the person. | Add at least one of them so we can find the email. See [Input record](https://developer.dropcontact.com/en/reference/input-record/). |
| `empty_field` | Warning | Some fields were sent empty. | Fill them in, or don't send them. |
| `only_organization_data` | Warning | The record has a company but no person, so only the company is enriched. | Nothing to do if this is what you want. |

If every record of the request has an error, the API answers with a `400` error instead, for accounts that have the `API_ERROR` option. This option is on by default for accounts created since June 1, 2026.