> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enrow.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Gestion des erreurs
> Gérez les erreurs de l'API Enrow avec élégance — formats de réponse, codes de statut, logique de réessai et bonnes pratiques
L'API Enrow signale les problèmes à l'aide de codes de statut HTTP et d'un corps d'erreur JSON. Ce guide explique les formats de réponse d'erreur, les erreurs les plus courantes et comment les corriger, ainsi que la façon de construire une logique de réessai fiable. Pour la liste complète des codes, consultez [Codes de statut](/fr/status-codes).
## À quoi ressemble une réponse d'erreur ?
La plupart des erreurs de l'API Enrow renvoient un simple objet JSON contenant un unique champ `message` :
```json theme={null}
{
"message": "Human-readable error description"
}
```
La seule exception est une erreur de **crédits insuffisants (402)** sur les endpoints **uniques** (recherche d'e-mail/de téléphone unique, vérification unique), qui renvoie un champ `reason` accompagné de `success` :
```json theme={null}
{
"reason": "Insufficient credits",
"success": false
}
```
Les réponses d'erreur n'incluent jamais les champs `error`, `status` ou `retry_after`. Lisez le code de statut HTTP pour orienter votre logique, et lisez `message` (ou `reason`) pour obtenir la description lisible par un humain.
## Quelles sont les erreurs les plus courantes et comment les corriger ?
Les erreurs ci-dessous couvrent la grande majorité des requêtes échouées. Chacune est accompagnée du corps de réponse renvoyé par l'API et de la solution à appliquer.
### Pourquoi est-ce que je reçois une erreur 400 Bad Request ?
Un `400` signifie que la charge utile de la requête est mal formée ou qu'un paramètre requis est manquant :
```json theme={null}
{
"message": "both company_domain and company_name are absent, input payload needs at least one of them"
}
```
**Solution** : vérifiez que vous fournissez tous les paramètres requis pour l'endpoint. Par exemple, [Rechercher e-mail](/fr/api-reference/email-finder/find-single) nécessite `fullname` ainsi que `company_domain` ou `company_name`.
### Pourquoi est-ce que je reçois une erreur 401 Unauthorized ?
Un `401` signifie que la clé API est manquante ou invalide :
```json theme={null}
{
"message": "This apikey is not valid"
}
```
**Solution** : vérifiez que la clé API est correcte et qu'elle est envoyée dans l'en-tête `x-api-key` (et non `Authorization`). Consultez [Authentification](/fr/authentication) pour savoir comment transmettre la clé à chaque requête.
### Pourquoi est-ce que je reçois une erreur 402 Insufficient Credits ?
Un `402` signifie que le compte ne dispose pas d'assez de crédits pour exécuter la requête :
```json theme={null}
{
"reason": "Insufficient credits",
"success": false
}
```
Sur les endpoints **groupés**, le même `402` est renvoyé avec le format standard `{ "message": "..." }`.
**Solution** : vérifiez le solde de crédits sur le [Tableau de bord](https://app.enrow.io) ou via `GET /account/info`. Rechargez des crédits ou mettez à niveau le forfait sur [enrow.io/pricing](https://enrow.io/pricing). Consultez [Crédits et facturation](/fr/credits-billing) pour savoir comment les crédits sont consommés par endpoint.
### Pourquoi est-ce que je reçois une erreur 429 Rate Limit Exceeded ?
Un `429` signifie que trop de requêtes ont été envoyées dans un court laps de temps :
```json theme={null}
{
"message": "Too Many Requests"
}
```
**Solution** : attendez et réessayez avec un backoff exponentiel. Consultez [Limites de débit](/fr/rate-limits) pour connaître les limites par forfait.
### Pourquoi est-ce que je reçois une erreur 500 Internal Server Error ?
Un `500` signifie qu'une erreur s'est produite du côté d'Enrow :
```json theme={null}
{
"message": "An unexpected error occurred"
}
```
**Solution** : réessayez la requête avec un backoff. Si le problème persiste, contactez [api@enrow.io](mailto:api@enrow.io).
## Comment gérer les erreurs dans le code ?
Vérifiez le statut HTTP avant d'analyser le corps de succès, puis levez une erreur qui transporte le code de statut afin que votre logique de réessai puisse s'y appuyer. Le champ `message` contient la description pour la plupart des erreurs, et `reason` la contient pour les réponses `402` des endpoints uniques.
```javascript Node.js theme={null}
async function findEmail(contact) {
const response = await fetch('https://api.enrow.io/email/find/single', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ENROW_API_KEY
},
body: JSON.stringify(contact)
});
if (!response.ok) {
const body = await response.json();
const error = new Error(`Enrow API error ${response.status}: ${body.message || body.reason}`);
error.status = response.status;
throw error;
}
return await response.json();
}
```
```python Python theme={null}
import requests
import os
def find_email(contact):
response = requests.post(
"https://api.enrow.io/email/find/single",
json=contact,
headers={
"Content-Type": "application/json",
"x-api-key": os.getenv("ENROW_API_KEY")
}
)
if not response.ok:
error = response.json()
message = error.get("message") or error.get("reason")
raise Exception(f"Enrow API error {response.status_code}: {message}")
return response.json()
```
## Comment réessayer les requêtes échouées ?
Ne réessayez que les erreurs qui valent la peine d'être réessayées — `429` et `5xx` — et appliquez un backoff exponentiel entre les tentatives. Les erreurs client de la plage `4xx` (sauf `429`) signalent un problème lié à la requête elle-même : les réessayer ne servira donc à rien.
```javascript theme={null}
async function requestWithRetry(fn, maxRetries = 3, baseDelay = 1000) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
const isLastAttempt = attempt === maxRetries - 1;
// Don't retry client errors (except rate limits)
if (error.status >= 400 && error.status < 500 && error.status !== 429) {
throw error;
}
if (isLastAttempt) throw error;
const delay = baseDelay * Math.pow(2, attempt);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
```
## Bonnes pratiques
* **Ne réessayez pas les erreurs 4xx** (sauf 429) — corrigez plutôt la requête
* **Réessayez les erreurs 429** — temporisez avec des délais exponentiels avant de réessayer
* **Réessayez les erreurs 5xx** — avec un backoff exponentiel
* **Utilisez les webhooks** plutôt que le polling pour éviter d'atteindre inutilement les limites de débit — consultez [Comment fonctionnent les webhooks](/fr/how-webhooks-work)
* **Journalisez les erreurs avec leur contexte** — incluez l'endpoint, les paramètres et l'horodatage pour faciliter le débogage
## FAQ
Sur les endpoints uniques (recherche d'e-mail/de téléphone unique, vérification unique), un `402` renvoie `{ "reason": "Insufficient credits", "success": false }`. Sur les endpoints groupés, le même `402` renvoie le format standard `{ "message": "..." }`. Lire à la fois `message` et `reason` (comme le font les exemples de code) gère les deux cas.
Réessayez les erreurs `429` (limite de débit) et `5xx` (serveur) avec un backoff exponentiel. Ne réessayez pas les autres erreurs `4xx` telles que `400`, `401` ou `402` — elles indiquent un problème lié à la requête, à la clé API ou au solde de crédits qu'un simple réessai ne résoudra pas.
Non. Les réponses d'erreur n'incluent jamais les champs `retry_after`, `error` ou `status`. Utilisez votre propre backoff exponentiel entre les réessais. Consultez [Limites de débit](/fr/rate-limits) pour connaître les limites applicables à votre forfait.
Pour la plupart des erreurs, la description se trouve dans le champ `message`. Pour un `402` de crédits insuffisants sur un endpoint unique, elle se trouve plutôt dans le champ `reason`. Orientez toujours votre logique en fonction du code de statut HTTP plutôt qu'en analysant le texte du message.
## Prochaines étapes
La liste complète des codes de statut HTTP et leur signification.
Comprenez les limites de requêtes par forfait pour éviter les erreurs 429.
Comment transmettre votre clé API dans l'en-tête x-api-key.
Découvrez comment les crédits sont consommés pour chaque endpoint.