## Vérifiez toujours `success`

Un code `200` ne veut pas toujours dire que votre requête a réussi. Lisez toujours le champ `success` de la réponse.

Tant que votre lot est en cours de traitement, `GET /v1/enrich/all/{request_id}` répond `200` avec `"success": false` et le message `Request not ready yet, try again in 30 seconds`. Il répond de la même façon quand le `request_id` est inconnu, ou quand nous avons un problème temporaire de notre côté.

Récupérez vos résultats dans les 30 jours : passé ce délai, ils peuvent ne plus être disponibles.

**Quoi faire :** attendez 30 secondes et réessayez. Pour ne pas interroger l'API en boucle, utilisez un [webhook](https://developer.dropcontact.com/fr/webhooks/), ou ajoutez `forceResults=true` pour récupérer les contacts déjà enrichis.

## Où lire le message d'erreur

La plupart des erreurs ressemblent à ceci. Le message est dans `reason` :

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

Certaines erreurs (`404`, `422`, `500`, et les erreurs de `GET /v1/account/credits`) mettent le message dans `detail` :

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

Les messages sont toujours en anglais.

## Erreurs par code

### 400 Bad Request

Votre requête n'est pas valide. Retournée par `POST /v1/enrich/all`.

| Message | Quoi faire |
| --- | --- |
| `Missing data in JSON` | Envoyez au moins un contact dans `data`. |
| `Too many records, you can only submit up to 250 records` | Découpez vos contacts en lots de 250 maximum. |
| `Data size is too big, you can only submit up to 15 kB of data in a single record` | Allégez le contact. Des `custom_fields` trop gros en sont souvent la cause. Voir [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/). |
| `Request contains invalid input` | Tous les contacts sont en erreur. Lisez `data[].errors` pour chaque contact. |

### 401 Unauthorized

Votre clé API est absente ou n'est pas valide. Retournée par tous les endpoints.

| Message | Quoi faire |
| --- | --- |
| `No api key received. Please set 'X-Access-Token' header with your api key as value.` ou `no-credentials` | Ajoutez l'en-tête `X-Access-Token` à votre requête. Voir [Authentification](https://developer.dropcontact.com/fr/authentication/). |
| `Unknown account` ou `invalid-api-key` | Votre clé API est fausse ou désactivée. Vérifiez-la dans l'[app Dropcontact](https://app.dropcontact.com/api). |

### 403 Forbidden

Votre clé API est valide, mais l'action est refusée.

| Message | Endpoints | Quoi faire |
| --- | --- | --- |
| `Sorry, you must contact the support to enable your API access!` | `POST /v1/enrich/all` | Contactez support@dropcontact.com pour activer l'accès à l'API. |
| `You submitted X valid items but only have Y credits left` | `POST /v1/enrich/all` | [Achetez des crédits](https://app.dropcontact.com/pricing), ou envoyez moins de contacts. Voir [Politique de crédits](https://developer.dropcontact.com/fr/credits/). |
| `Unknown account` | Tous sauf `GET /v1/account/credits` | Votre compte n'est pas encore prêt pour l'API. Connectez-vous une fois à l'[app Dropcontact](https://app.dropcontact.com), puis contactez le support si le problème continue. |
| `This request id was not sent by you` | `GET /v1/enrich/all/{request_id}` | Ce `request_id` appartient à un autre compte. Vérifiez que vous utilisez la bonne clé API. |

### 404 Not Found

| Message | Endpoints | Quoi faire |
| --- | --- | --- |
| `No webhook callback found` | `DELETE /v1/enrich/webhook` | Il n'y a pas d'URL de webhook par défaut à supprimer. Rien à faire. Voir [Webhooks](https://developer.dropcontact.com/fr/webhooks/). |
| `Not Found` | Tous | L'URL appelée n'existe pas. Vérifiez-la, par exemple `/v1/enrich/all` et non `/v1/all`. |

### 422 Validation Error

Le corps de la requête ou un paramètre n'a pas le bon format.

`detail` liste chaque champ en erreur. Corrigez votre requête à l'aide de la [référence de l'API](https://developer.dropcontact.com/fr/reference/).

C'est aussi le cas quand `custom_callback_url` ou l'URL de webhook par défaut n'est pas une URL valide, ou fait plus de 2 083 caractères. Voir [Webhooks](https://developer.dropcontact.com/fr/webhooks/).

### 429 Too Many Requests

Vous avez envoyé trop de requêtes en peu de temps (voir [Limites de requêtes](https://developer.dropcontact.com/fr/rate-limits/)), ou nous avons un problème temporaire de notre côté. Le message est `please retry in a few seconds`.

**Quoi faire :** attendez quelques secondes et réessayez, en laissant plus de temps entre chaque essai.

### 500 Internal Server Error

Une erreur s'est produite de notre côté, et nous sommes prévenus automatiquement. Le message est `An error occurred. Please retry later.`

**Quoi faire :** réessayez plus tard. Si le problème continue, contactez support@dropcontact.com.

### 502, 503, 504

Ces erreurs viennent de notre réseau, devant l'API : maintenance ou délai dépassé.

**Quoi faire :** réessayez plus tard.

## Erreurs et avertissements par contact

Certains problèmes ne concernent qu'un seul contact. La requête réussit quand même, et le problème est indiqué dans `data[].errors` ou `data[].warnings` pour ce contact.

| Clé | Type | Ce que ça veut dire | Quoi faire |
| --- | --- | --- | --- |
| `unexpected_field` | Erreur | Certains champs ne sont pas reconnus et sont ignorés. Le contact est quand même traité. | Corrigez les noms des champs indiqués. Voir [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/). |
| `only_contact_data` | Erreur | Le contact a une personne, mais aucun identifiant d'entreprise (company, website, company_linkedin, num_siren, siret), aucun email et aucun profil LinkedIn de la personne. | Ajoutez au moins l'une de ces informations pour que nous puissions trouver l'email. Voir [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/). |
| `empty_field` | Avertissement | Certains champs ont été envoyés vides. | Remplissez-les, ou ne les envoyez pas. |
| `only_organization_data` | Avertissement | Le contact a une entreprise, mais pas de personne : seule l'entreprise est enrichie. | Rien à faire si c'est voulu. |

Si tous les contacts de la requête ont une erreur, l'API répond à la place par une erreur `400`, pour les comptes qui ont l'option `API_ERROR`. Cette option est activée par défaut pour les comptes créés depuis le 1er juin 2026.