Codes d'erreur
Un verdict invalid n'est pas une erreur : une validation qui aboutit répond toujours 200, quel que soit le verdict. Les codes ci-dessous signalent un appel qui n'a pas pu être traité.
Format
Toutes les erreurs JSON ont la même forme :
{
"statusCode": 402,
"message": "Insufficient credits for SMTP validation",
"code": "INSUFFICIENT_CREDITS",
"timestamp": "2026-10-15T09:12:44.512Z",
"path": "/v2/email/validate"
}
| Champ | Présence | Contenu |
|---|---|---|
statusCode | toujours | Code HTTP |
message | toujours | Texte lisible, ou tableau de textes pour une erreur de validation du corps |
code | parfois | Code machine stable : c'est lui qu'il faut tester |
details | parfois | Données structurées liées au code |
timestamp, path | toujours | Horodatage et chemin appelé |
Les messages peuvent être reformulés ; les code ne changent pas. Seule exception au format JSON : le 429 du limiteur de débit par IP, en texte brut.
Récapitulatif
| HTTP | Code stable | Cause | Réessayer ? |
|---|---|---|---|
400 | — | Corps invalide ou champ inconnu | Non |
401 | — | Authentification absente, invalide ou révoquée | Non |
402 | INSUFFICIENT_CREDITS | Solde épuisé pour un SMTP | Après recharge |
403 | — | Restriction d'IP ou d'origine de la clé, captcha du widget, IP bloquée | Non |
404 | — | Ressource introuvable (widget inexistant ou désactivé) | Non |
413 | — | Corps de requête trop gros | Non |
429 | API_KEY_RATE_LIMITED | Limite d'appels de la clé atteinte (minute, heure ou jour) | Après Retry-After |
429 | API_KEY_BUDGET_EXCEEDED | Plafond de crédits de la clé atteint | Après Retry-After |
429 | — | Limite de débit (IP ou widget), ou trop de requêtes simultanées | Après Retry-After, ou en réduisant le parallélisme |
5xx | — | Incident de notre côté | Oui, avec délai croissant |
Les outils du serveur MCP renvoient leurs erreurs dans le résultat de l'outil, avec leurs propres codes : voir Assistants IA.
Détail
400 Bad Request
Le corps ne respecte pas le format attendu. message est alors un tableau :
{
"statusCode": 400,
"message": ["email must be an email"],
"timestamp": "2026-10-15T09:12:44.512Z",
"path": "/v2/email/validate"
}
Causes fréquentes :
email must be an email: la valeur n'est pas une adresse au format attendu par le validateur. Pour qualifier une saisie douteuse sans erreur, filtrez les valeurs vides ou sans@avant l'appel.property xxx should not exist: un champ inconnu a été envoyé. Le corps dePOST /v2/email/validaten'accepte queemail,smtp,enrichment,smtpTimeoutetcountry(plus les champs internes du widget).smtpTimeout must not be less than 1000ougreater than 30000.
401 Unauthorized
message | Cause |
|---|---|
No authorization header | En-tête Authorization absent, ou clé envoyée dans X-API-Key, qui n'est pas lu |
Invalid or revoked API key | Clé inconnue, révoquée, ou ancien secret après une rotation dont la période de grâce est écoulée |
Invalid authorization format | Valeur qui n'est ni une clé ywc_live_ / ywc_test_, ni un jeton de session valide |
Unauthorized | Route réservée au tableau de bord appelée avec une clé API (traitement par lots, gestion des clés…) |
402 INSUFFICIENT_CREDITS
Le SMTP est activé sur la clé et le solde de l'organisation est à zéro. L'appel est refusé avant toute vérification et rien n'est débité. Rechargez avec un pack depuis Crédits, ou passez du Starter au Pro. Voir Crédits.
403 Forbidden
message | Cause |
|---|---|
Access denied: IP address not allowed for this API key | L'IP appelante n'est pas dans allowedIps |
Access denied: Origin domain not allowed for this API key | L'en-tête Origin est absent ou hors de allowedDomains. Un appel serveur n'envoie pas d'Origin : voir Authentification |
Access denied: IP address and origin domain are not allowed for this API key | Les deux restrictions échouent |
CAPTCHA token required for this widget · CAPTCHA verification failed | Widget avec captcha appelé sans preuve valide |
This request is blocked for this widget | IP sur la liste de blocage du widget |
Les refus de restriction sont journalisés et visibles dans les statistiques de la clé.
413 Payload Too Large
Le corps dépasse la taille admise : 256 Ko pour un corps JSON, 15 Mo pour un fichier de traitement par lots. L'appel est refusé avant tout traitement.
{ "statusCode": 413, "message": "request entity too large" }
Une validation ne pèse que quelques centaines d'octets : un 413 signale presque toujours un corps mal construit (fichier envoyé en JSON, champ dupliqué en boucle). Pour une liste d'adresses, utilisez le traitement par lots.
429 API_KEY_RATE_LIMITED
La clé a atteint sa limite d'appels (60 par minute, 1 000 par heure, 10 000 par jour par défaut). L'appel refusé n'est pas facturé.
{
"statusCode": 429,
"message": "Limite d'appels de cette clé atteinte (60 par minute). Réessayez dans 42 s.",
"code": "API_KEY_RATE_LIMITED",
"details": { "window": "minute", "limit": 60, "retryAfterSeconds": 42 },
"timestamp": "2026-10-16T18:00:00.000Z",
"path": "/v2/email/validate"
}
details.window vaut minute, hour ou day. Attendez Retry-After. Voir Limites de débit.
429 API_KEY_BUDGET_EXCEEDED
La clé a atteint son plafond de crédits ; le compte, lui, peut encore avoir du crédit.
{
"statusCode": 429,
"message": "Plafond journalier de cette clé atteint (500/500 crédits). Il se réinitialise à 00:00 UTC.",
"code": "API_KEY_BUDGET_EXCEEDED",
"details": { "window": "day", "limit": 500, "used": 500, "retryAfterSeconds": 21600 },
"timestamp": "2026-10-15T18:00:00.000Z",
"path": "/v2/email/validate"
}
details.window vaut day ou month. Attendez Retry-After, ou relevez le plafond dans Clés API. Recharger le solde n'y change rien.
429 limite de débit
- Par IP sur
POST /v2/email/validate(100/min) et sur les suggestions de domaine et de faute de frappe (60/min) : corps en texte brut, en-têtesRateLimit-*etRetry-After. Voir Limites de débit. - Anti-abus du widget :
{"statusCode": 429, "message": "Too many requests for this widget", …}avecRetry-After. - Requêtes simultanées : plus de 100 requêtes en cours en même temps depuis une même IP. Réponse HTML sans
Retry-After: réduisez le nombre d'appels en parallèle.
5xx
Un incident de notre côté. Réessayez une ou deux fois avec un délai croissant, consultez status.yeswecheck.fr, puis basculez en mode dégradé : acceptez l'adresse et revalidez-la plus tard.
Diagnostiquer
# L'API répond-elle ?
curl https://api.yeswecheck.fr/health
# La clé est-elle acceptée ? (gratuit avec une clé sans SMTP ; 1 crédit sinon)
curl -i https://api.yeswecheck.fr/v2/email/validate \
-H "Authorization: Bearer $YWC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'
Pour toute question au support ([email protected]), joignez l'endpoint, l'heure de l'appel, le corps de la réponse et, pour une validation aboutie, sa référence debug_ref. N'envoyez jamais votre clé.