Codes d’erreur

Un appel en échec renvoie un statut HTTP et une enveloppe JSON dont le champ code indique ce qui n’a pas fonctionné. Voici les 25 codes que l’API peut renvoyer. De nouveaux codes peuvent apparaître dans la v1 : traitez un code inconnu d’après son statut HTTP.

L’enveloppe d’erreur

Chaque corps d’erreur a cette forme ; code et message sont toujours présents.

Champ	Type	Obligatoire	Description
error	object	oui
error.code	string	oui	Machine-readable error code. Each response lists the codes it can carry; new codes may be added within v1, so treat an unknown code by its HTTP status.
error.message	string	oui	Human-readable explanation (English).
error.requestId	string	non	The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1.
error.detail	object	non	Structured context for the error, such as the offending field; omitted when there is none. noms de membres libres
error.docs	string	non	Where the error codes are explained. Sent since v1.1. format uri

Une vraie réponse d’erreur, pour une requête qui omet le champ obligatoire :

curl

curl -sS 'https://ecdsa.com/api/v1/jwt/decode' \
  -H 'content-type: application/json' \
  -d '{}'

Réponse 400

{
  "error": {
    "code": "missing_field",
    "message": "Field \"token\" is required and must be a non-empty string.",
    "requestId": "docs-example",
    "docs": "https://ecdsa.com/developers#errors"
  }
}

Tous les codes

Code	HTTP	Signification	Quand il survient	Que faire	SDK
invalid_json	400	The body is not valid JSON or not a JSON object; or the input nests arrays and objects more than 64 levels deep (JSON documents inside string fields count too), or is too complex to inspect for private keys.	Causes typiques : un corps au format formulaire ou en texte brut au lieu de JSON, un tableau ou une chaîne JSON au premier niveau, ou une entrée générée avec une imbrication très profonde. L’en-tête content-type n’a aucune importance ; seul le corps compte. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Envoyez un seul objet JSON comme corps. Si l’entrée est générée, vérifiez son imbrication.	Non retenté
missing_field	400	A required field is absent or empty.	Un champ requis par l’opération est absent, null, vide ou n’est pas une chaîne, souvent parce que son nom est écrit différemment, par exemple public_key au lieu de publicKey. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Ajoutez le champ indiqué par le message ; la page de référence de l’opération répertorie les champs obligatoires.	Non retenté
invalid_input	400	A field could not be parsed — the message explains exactly why.	Un champ est présent mais ne peut pas être interprété : une clé, une signature, un jeton ou un certificat dans un encodage ou un format que l’opération ne reconnaît pas. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, Create a webhook endpoint	Lisez le message : il indique le champ et la raison. Vérifiez l’encodage (hexadécimal, base64, PEM) et, pour les signatures, la courbe.	Non retenté
private_key_rejected	400	The request contains private-key material (a PEM PRIVATE KEY block, an OpenSSH, SSH2 or PuTTY private key, or a JWK with "d"). Never send private keys anywhere.	Un fichier de clé complet collé là où seule la moitié publique est nécessaire : un PEM PKCS#8 ou SEC1, une clé privée OpenSSH ou PuTTY, une JWK qui contient encore « d », même lorsque la clé est imbriquée dans une chaîne qui contient du JSON. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	N’envoyez que des données publiques. Pour travailler avec une clé privée, utilisez les outils qui fonctionnent dans le navigateur : ils s’exécutent sur votre machine et n’envoient rien.	Non retenté
unsupported_algorithm	400	The token's algorithm is not one this operation verifies.	Un JWT dont l’opération ne vérifie pas l’algorithme : HS, RS, PS*, EdDSA, ES256K ou none. Opérations : Verify an ES256/ES384/ES512 JWT signature	Cette API vérifie ES256, ES384 et ES512. Vérifiez les autres algorithmes en local avec une bibliothèque JWT : un secret HMAC ne doit jamais être envoyé nulle part.	Non retenté
invalid_domain	400	Not a public DNS hostname (IP addresses, single-label names and paths are refused).	Le segment de chemin est une adresse IP, un nom sans point comme localhost, ou un texte qui n’est pas un nom d’hôte. Un schéma, un port ou un chemin autour du nom est d’abord retiré. Opérations : TLS signature-health grade for a domain	Envoyez un nom d’hôte public, par exemple `github.com`. Les adresses IP et les noms internes ne peuvent pas être analysés d’ici.	Non retenté
scan_dns_error	400	The domain does not resolve in public DNS.	La résolution du nom dans le DNS public échoue : domaine inexistant (faute de frappe, enregistrement expiré, nom connu seulement d’un DNS interne), aucun enregistrement A ou AAAA, ou défaillance du DNS. Opérations : TLS signature-health grade for a domain	Vérifiez l’orthographe du nom et assurez-vous qu’il possède des enregistrements A ou AAAA.	Non retenté
scan_private_address	400	The domain resolves (at least partly) to a private or reserved address.	Une adresse du nom (IPv4, IPv6 ou IPv4 intégrée à une IPv6) se trouve dans une plage privée ou réservée, comme un réseau interne ou la boucle locale. Un mélange d’adresses publiques et privées est refusé en bloc. Opérations : TLS signature-health grade for a domain	Vérifiez un hôte joignable depuis l’Internet public : les hôtes internes ne peuvent pas être analysés d’ici.	Non retenté
webhook_url_refused avec les clés d’API	400	The webhook URL cannot receive deliveries: it is not https on port 443, its host is not a public DNS name, or the name does not resolve or resolves (at least partly) to a private or reserved address.	Création d’un point de terminaison avec une URL http, un port autre que 443, une adresse IP ou un nom interne, ou avec un hôte dont la réponse DNS contient une adresse privée ou réservée, même si une seule de ses adresses l’est. Opérations : Create a webhook endpoint	Utilisez une URL https sur le port par défaut, avec un nom d’hôte public. Le message indique quelle règle l’URL a enfreinte et, pour une adresse refusée, quelle adresse et quelle plage sont en cause.	Non retenté
unauthorized	401	The Authorization or X-API-Key header is malformed, the API key is not valid (wrong checksum, unknown, revoked or expired), or the operation needs a key.	Un en-tête `Authorization` ou `X-API-Key` est présent mais mal formé, et, une fois les clés d’API lancées, une clé inconnue, révoquée ou expirée. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Supprimez l’en-tête pour appeler l’API de façon anonyme, ou envoyez une clé complète et valide.	Non retenté
forbidden_scope avec les clés d’API	403	The API key is valid but lacks a scope this operation requires; the message names it.	Une clé créée sans le scope dont une opération a besoin, par exemple une clé qui n’a que le scope api et qui appelle l’opération de santé des domaines, laquelle exige le scope scan. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Appelez avec une clé qui possède ce scope.	Non retenté
webhook_limit_reached avec les clés d’API	403	The account already has as many webhook endpoints as its plan allows.	Création d’un point de terminaison alors que le compte en a déjà autant que son offre le permet ; l’offre gratuite en autorise un. Opérations : Create a webhook endpoint	Supprimez un point de terminaison dont vous n’avez plus besoin, ou recréez le point de terminaison existant avec la même URL pour modifier sa description ou ses événements.	Non retenté
not_found	404	No operation exists at this path.	Un chemin sous `/api/v1` qui ne désigne aucune opération : une faute de frappe, un segment manquant ou en trop. Toute opération peut le renvoyer.	Comparez le chemin à la référence de l’API ; les opérations se trouvent sous `/api/v1`.	Non retenté
webhook_not_found avec les clés d’API	404	The API key's account has no webhook endpoint with this id.	Un ID de point de terminaison qui n’appartient pas au compte de la clé : déjà supprimé, mal saisi ou appartenant à un autre compte. Opérations : Delete a webhook endpoint, Send a test event	Listez les points de terminaison du compte avec GET `/api/v1/webhooks` et utilisez l’un des ID obtenus.	Non retenté
method_not_allowed	405	The path exists but does not accept this HTTP method; see the Allow header.	Appel d’une opération POST avec GET (par exemple en l’ouvrant dans la barre d’adresse d’un navigateur), ou l’inverse. Toute opération peut le renvoyer.	Utilisez une méthode indiquée dans l’en-tête `Allow` : POST pour les opérations qui prennent un corps JSON, GET pour les autres.	Non retenté
payload_too_large	413	The body exceeds 100 KB.	Le corps dépasse 100 Ko, généralement parce que tout un lot de certificats ou un fichier entier a été collé dans un seul champ. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Envoyez moins de données par appel : une chaîne de certificats, un jeton.	Non retenté
rate_limited	429	Too many requests — see Retry-After.	Trop de requêtes dans la fenêtre en cours : par IP sans clé, par clé si vous en utilisez une. Les analyses réelles d’un domaine puisent aussi dans des budgets par hôte et globaux. Opérations : API self-description, Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Attendez le nombre de secondes indiqué dans `Retry-After`, puis réessayez, et mettez les réponses en cache de votre côté.	Retenté jusqu’à 2 fois
quota_exceeded avec les clés d’API	429	A daily or monthly quota of the API key's account is used up. X-Quota-Reset (and Retry-After) say when it starts over; retrying earlier cannot succeed.	Les appels effectués avec une clé ont épuisé les unités de quota quotidiennes ou mensuelles du compte, ou ses analyses de domaines quotidiennes ; les clés de test ont leurs propres quotas, plus petits. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Ne réessayez pas avant l’heure indiquée dans `X-Quota-Reset` : le quota repart de zéro à ce moment-là, pas avant.	Non retenté
internal_error	500	Unexpected server error.	Une erreur que l’API n’avait pas anticipée. Elle est journalisée avec l’ID de requête, jamais avec le corps de la requête. Toute opération peut le renvoyer.	Si elle persiste, communiquez la valeur `requestId` du corps d’erreur.	Non retenté
scan_unreachable	502	The domain refused or dropped the connection on port 443.	Le nom est résolu, mais aucune connexion TCP sur le port 443 n’aboutit depuis Internet : pas de serveur HTTPS, un pare-feu qui la refuse ou l’abandonne, ou un hôte hors service. Opérations : TLS signature-health grade for a domain	Vérifiez que l’hôte est accessible en HTTPS sur le port 443 depuis l’Internet public.	Retenté jusqu’à 2 fois
scan_tls_error	502	The TLS handshake failed or presented no usable certificate.	Une connexion s’ouvre sur le port 443, mais le handshake TLS se termine par une alerte ou une incompatibilité de protocole, ou le serveur n’envoie aucun certificat lisible par le scanner. Opérations : TLS signature-health grade for a domain	Vérifiez la configuration TLS du serveur, par exemple avec le rapport de santé du domaine.	Retenté jusqu’à 2 fois
service_unavailable avec les clés d’API	503	API keys cannot be verified right now (the key store is unreachable); retry shortly.	Le magasin de clés est injoignable : une clé présentée ne peut donc pas être vérifiée. Un appel qui présente une clé n’est jamais traité de façon anonyme. Opérations : Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, TLS signature-health grade for a domain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Réessayez sous peu, comme le font les SDK.	Retenté jusqu’à 2 fois
webhooks_unavailable avec les clés d’API	503	Webhooks are switched off on this server: it has no signing keys configured.	Aucune clé de signature de webhook n’est configurée sur le serveur, qui ne peut donc pas signer les envois ; chaque opération de webhook renvoie ce code tant qu’aucune clé n’est définie. Opérations : List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Rien à modifier dans la requête : les webhooks sont désactivés sur ce serveur pour le moment. Réessayez plus tard.	Retenté jusqu’à 2 fois
scan_timeout	504	The scan did not finish in time.	La résolution du nom, la connexion ou le handshake TLS a pris plus de temps que le scanner ne l’autorise : hôte lent ou surchargé, ou paquets ignorés silencieusement. Opérations : TLS signature-health grade for a domain	Réessayez plus tard ; les hôtes lents ou surchargés peuvent dépasser le délai imparti.	Retenté jusqu’à 2 fois
timeout	504	The operation did not finish within its time budget.	Le traitement de la requête a dépassé le délai imparti de 10 secondes. Une entrée qui respecte les limites des requêtes n’est pas censée provoquer cela. Opérations : API self-description, Verify an ECDSA signature, Convert a signature between DER and raw r‖s, Decode a JWT (no signature check), Verify an ES256/ES384/ES512 JWT signature, Decode an X.509 certificate or chain, List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Réessayez une fois ; si la même entrée dépasse à nouveau le délai, communiquez la valeur `requestId` du corps d’erreur.	Retenté jusqu’à 2 fois

Nouvelles tentatives

Les SDK officiels retentent les erreurs 429 (sauf quota_exceeded), 502, 503 et 504, au plus 2 fois, en attendant aussi longtemps que le demande Retry-After (au plus 60 secondes), et sinon selon un backoff exponentiel avec gigue complète. Chaque opération est une fonction pure de son entrée : une nouvelle tentative est donc toujours sans risque, et votre propre client peut suivre la même règle.