Aller au contenu principal

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"
}
ChampPrésenceContenu
statusCodetoujoursCode HTTP
messagetoujoursTexte lisible, ou tableau de textes pour une erreur de validation du corps
codeparfoisCode machine stable : c'est lui qu'il faut tester
detailsparfoisDonnées structurées liées au code
timestamp, pathtoujoursHorodatage 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​

HTTPCode stableCauseRéessayer ?
400—Corps invalide ou champ inconnuNon
401—Authentification absente, invalide ou révoquéeNon
402INSUFFICIENT_CREDITSSolde épuisé pour un SMTPAprès recharge
403—Restriction d'IP ou d'origine de la clé, captcha du widget, IP bloquéeNon
404—Ressource introuvable (widget inexistant ou désactivé)Non
413—Corps de requête trop grosNon
429API_KEY_RATE_LIMITEDLimite d'appels de la clé atteinte (minute, heure ou jour)Après Retry-After
429API_KEY_BUDGET_EXCEEDEDPlafond de crédits de la clé atteintAprès Retry-After
429—Limite de débit (IP ou widget), ou trop de requêtes simultanéesAprè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 de POST /v2/email/validate n'accepte que email, smtp, enrichment, smtpTimeout et country (plus les champs internes du widget).
  • smtpTimeout must not be less than 1000 ou greater than 30000.

401 Unauthorized​

messageCause
No authorization headerEn-tête Authorization absent, ou clé envoyée dans X-API-Key, qui n'est pas lu
Invalid or revoked API keyClé inconnue, révoquée, ou ancien secret après une rotation dont la période de grâce est écoulée
Invalid authorization formatValeur qui n'est ni une clé ywc_live_ / ywc_test_, ni un jeton de session valide
UnauthorizedRoute 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​

messageCause
Access denied: IP address not allowed for this API keyL'IP appelante n'est pas dans allowedIps
Access denied: Origin domain not allowed for this API keyL'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 keyLes deux restrictions échouent
CAPTCHA token required for this widget · CAPTCHA verification failedWidget avec captcha appelé sans preuve valide
This request is blocked for this widgetIP 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êtes RateLimit-* et Retry-After. Voir Limites de débit.
  • Anti-abus du widget : {"statusCode": 429, "message": "Too many requests for this widget", …} avec Retry-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é.