Gérer les erreurs
Ce que veut dire chaque erreur de l'API Dropcontact, et quoi faire.
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, 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 :
{
"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 :
{
"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é. |
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. |
Unknown account ou invalid-api-key | Votre clé API est fausse ou désactivée. Vérifiez-la dans l'app Dropcontact. |
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, ou envoyez moins de contacts. Voir Politique de crédits. |
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, 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. |
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.
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.
429 Too Many Requests
Vous avez envoyé trop de requêtes en peu de temps (voir Limites de requêtes), 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é. |
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é. |
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.