Gestion des erreurs

L'API utilise les codes de statut HTTP standards et retourne des réponses d'erreur structurées.

Format de réponse d'erreur

{
  "error": {
    "code": "error_code",
    "message": "Description lisible de l'erreur"
  },
  "request_id": "req_abc123"
}

Codes de statut HTTP

| Statut | Signification | Quand | |---|---|---| | 200 | OK | Requête réussie | | 400 | Bad Request | Paramètres manquants ou invalides | | 401 | Unauthorized | Clé API invalide ou manquante | | 429 | Too Many Requests | Limite de débit dépassée | | 500 | Internal Server Error | Erreur côté serveur |

Codes d'erreur

bad_request

La requête manque de paramètres requis ou contient des données invalides.

{
  "error": {
    "code": "bad_request",
    "message": "email or domain parameter is required"
  }
}

unauthorized

La clé API est manquante, invalide ou révoquée.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

rate_limited

Vous avez dépassé la limite de débit de votre plan.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Consultez l'en-tête X-RateLimit-Reset pour savoir quand réessayer. Voir Limites de débit pour plus de détails.

internal_error

Une erreur inattendue s'est produite de notre côté.

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Si cela persiste, contactez le support avec votre request_id.

Bonnes pratiques

1. Vérifiez toujours le code de statut HTTP avant d'analyser le corps de la réponse
2. Implémentez un backoff exponentiel pour les erreurs 429 et 500
3. Loggez le request_id pour le débogage et les demandes de support
4. Gérez les erreurs réseau gracieusement — timeouts, échecs DNS, etc.