Handling errors
What each Dropcontact API error means and what to do about it.
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, 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:
{
"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:
{
"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. |
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. |
Unknown account or invalid-api-key | Your API key is wrong or disabled. Check it in the Dropcontact app. |
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, or send fewer records. See Credits Policy. |
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, 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. |
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.
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.
429 Too Many Requests
You sent too many requests in a short time (see 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. |
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. |
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.