Codes d'erreur & Debugging

Codes HTTP

Code	Nom	Signification
200	OK	Succès
201	Created	Ressource créée
204	No Content	Succès sans corps de réponse
400	Bad Request	Données invalides ou manquantes
401	Unauthorized	Token/API Key manquant ou invalide
402	Payment Required	Crédits SMTP insuffisants
403	Forbidden	Permissions insuffisantes
404	Not Found	Ressource introuvable
409	Conflict	Conflit (ex: job batch déjà actif)
422	Unprocessable Entity	Erreur de validation des données
429	Too Many Requests	Rate limit dépassé
500	Internal Server Error	Erreur serveur

Format des erreurs

{
  "message": "Description lisible de l'erreur",
  "code": "ERROR_CODE",
  "statusCode": 400
}

Pour les erreurs de validation (422), message est un tableau :

{
  "message": [
    "email must be an email",
    "smtp must be a boolean"
  ],
  "error": "Unprocessable Entity",
  "statusCode": 422
}

Erreurs courantes

401 — Non authentifié

{ "message": "Unauthorized", "statusCode": 401 }

Causes possibles :

• Token JWT expiré → utiliser /auth/refresh
• API Key invalide ou révoquée → vérifier dans le Dashboard
• Header manquant → ajouter X-API-Key ou Authorization: Bearer

---

402 — Crédits insuffisants

{
  "message": "Insufficient credits for SMTP validation",
  "code": "INSUFFICIENT_CREDITS",
  "statusCode": 402
}

→ Rechargez vos crédits depuis le Dashboard ou désactivez smtp: true

---

403 — Forbidden

{ "message": "Only owners and admins can create API keys", "statusCode": 403 }

→ Votre rôle est member. Demandez à un owner ou admin d'effectuer cette action.

---

409 — Job batch déjà actif

{
  "message": "A batch job is already running for this organization",
  "code": "ACTIVE_JOB_EXISTS",
  "statusCode": 409
}

→ Attendez la fin du job en cours ou annulez-le via POST /batch/{jobId}/cancel

---

422 — Validation des données

{
  "message": ["email must be an email"],
  "error": "Unprocessable Entity",
  "statusCode": 422
}

→ Vérifiez le format des données envoyées (voir le schéma dans l'API Reference)

---

429 — Rate limit

{
  "message": "Too many requests from this IP, please try again later",
  "statusCode": 429
}

→ Attendez Retry-After secondes avant de réessayer

---

Widget — 429 WIDGET_RATE_LIMIT

{
  "message": "Too many requests for this widget",
  "reason": "WIDGET_RATE_LIMIT",
  "retryAfterSeconds": 60
}

→ Protection anti-abus activée pour ce widget. Normal si un même device/IP fait trop de requêtes.

Statuts de validation email

Les statuts status dans /email/validate ne sont pas des erreurs HTTP mais des résultats métier :

Statut	Code HTTP	Signification
valid	200	Email valide ✅
invalid	200	Email invalide ❌
risky	200	Email risqué ⚠️
unknown	200	Impossible de vérifier 🟡

tip

Un statut invalid retourne toujours HTTP 200. C'est le résultat de la validation, pas une erreur.

Debugging

Vérifier le statut de l'API

curl https://api.yeswecheck.fr/health

{
  "status": "healthy",
  "timestamp": "2026-02-25T10:00:00.000Z",
  "version": "v2"
}

Tester une clé API

curl https://api.yeswecheck.fr/v2/credits/balance \
  -H "X-API-Key: ywc_live_votre_cle"

Si vous recevez un 401, la clé est invalide ou révoquée.

Inspecter les headers de réponse

curl -I -X POST https://api.yeswecheck.fr/v2/email/validate \
  -H "X-API-Key: ywc_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Logs d'usage

Consultez vos logs d'appels dans le Dashboard → Usage pour identifier les erreurs récurrentes.

Contacter le support

Si vous rencontrez une erreur 500 persistante ou un comportement inattendu :

• Email : [email protected]
• Incluez : votre organizationId, le timestamp, l'endpoint, et la réponse complète