Gestion des erreurs

L'API Meirra utilise les codes de statut HTTP standards pour indiquer la réussite ou l'échec des requêtes. En général : • **2xx** — Succès. La requête s'est déroulée comme prévu. • **4xx** — Erreur client. La requête est invalide ou ne peut pas être traitée. • **5xx** — Erreur serveur. Quelque chose a échoué de notre côté. Toutes les réponses d'erreur utilisent une structure JSON cohérente avec un code, un message et les détails utiles pour diagnostiquer et traiter le problème.

Toutes les erreurs suivent un format cohérent : ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Description lisible de l'erreur", "détails": { ... } } } ``` Le champ `code` est un identifiant lisible par machine que vous pouvez utiliser dans votre logique de gestion d'erreurs. Le `message` fournit une description lisible par un humain. L'objet optionnel `détails` contient un contexte supplémentaire propre au type d'erreur.

Les erreurs d'authentification surviennent lorsque votre clé d'API est absente, invalide ou sans permission. | Code | HTTP | Description | |------|------|-------------| | `INVALID_API_KEY` | 401 | Clé d'API absente ou invalide | | `API_KEY_REVOKED` | 401 | Clé d'API révoquée | | `IP_NOT_ALLOWED` | 403 | IP de la requête absente de la liste autorisée | **Exemple :** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "La clé d'API fournie est invalide ou absente" } } ``` **Comment résoudre :** Vérifiez que votre clé d'API est correcte et incluse dans l'en-tête `x-api-key`. Vérifiez si la clé a été révoquée dans le Tableau de bord développeur.

Les erreurs de solde surviennent quand votre compte n'a pas assez de crédits pour la requête. | Code | HTTP | Description | |------|------|-------------| | `INSUFFICIENT_BALANCE` | 402 | Solde trop bas pour la requête | **Exemple :** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Votre solde de $0.50 est insuffisant pour cette requête ($1.00 requis)", "détails": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **Comment résoudre :** Rechargez votre solde dans le Tableau de bord développeur. Configurez des alertes de solde bas pour éviter les coupures.

Les erreurs de limite de débit surviennent quand vous dépassez le rythme de requêtes autorisé. | Code | HTTP | Description | |------|------|-------------| | `RATE_LIMIT_EXCEEDED` | 429 | Trop de requêtes | **Exemple :** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Limite de débit dépassée. Réessayez dans 60 secondes.", "détails": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **Comment résoudre :** Implémentez un backoff exponentiel. Consultez l'en-tête `Retry-After` pour savoir quand réessayer. Étalez les requêtes dans le temps.

Les erreurs de validation surviennent quand les paramètres de la requête sont absents ou invalides. | Code | HTTP | Description | |------|------|-------------| | `INVALID_REQUEST` | 400 | Paramètres manquants ou invalides | | `INVALID_EMAIL` | 400 | Format d'e-mail invalide | | `BATCH_TOO_LARGE` | 400 | Lot dépassant la taille maximale | **Exemple :** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Échec de la validation de la requête", "détails": { "field": "email", "issue": "L'e-mail est obligatoire" } } } ``` **Comment résoudre :** Consultez le champ `détails` pour identifier l'erreur de validation précise. Assurez-vous que tous les champs requis sont fournis dans le format attendu.

Les erreurs de service surviennent quand quelque chose échoue dans notre infrastructure. | Code | HTTP | Description | |------|------|-------------| | `SERVICE_ERROR` | 500 | Échec interne du service | | `SERVICE_UNAVAILABLE` | 503 | Service temporairement indisponible | | `UPSTREAM_ERROR` | 502 | Une dépendance externe a échoué | **Exemple :** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "Une erreur interne s'est produite. Veuillez réessayer plus tard." } } ``` **Comment résoudre :** Ce sont des erreurs transitoires. Implémentez une logique de retry avec backoff exponentiel. Si les erreurs persistent, consultez la page de statut ou contactez le support.