Fehlercodes

Ein fehlgeschlagener Aufruf antwortet mit einem HTTP-Status und einem JSON-Fehlerobjekt, dessen Feld code sagt, was schiefgelaufen ist. Das sind alle 25 Codes, die die API senden kann. Innerhalb von v1 können neue Codes hinzukommen: Behandle einen unbekannten Code nach seinem HTTP-Status.

Das Fehlerobjekt

Jeder Fehler-Body hat diese Struktur; code und message sind immer vorhanden.

Feld	Typ	Erforderlich	Beschreibung
error	object	ja
error.code	string	ja	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	ja	Human-readable explanation (English).
error.requestId	string	nein	The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1.
error.detail	object	nein	Structured context for the error, such as the offending field; omitted when there is none. beliebige Feldnamen
error.docs	string	nein	Where the error codes are explained. Sent since v1.1. Format uri

Eine echte Fehlerantwort – der Anfrage fehlt das Pflichtfeld:

curl

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

Antwort 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"
  }
}

Alle Codes

Code	HTTP	Bedeutung	Wann er auftritt	Was zu tun ist	SDKs
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.	Typische Ursachen: ein als Formulardaten kodierter Body oder reiner Text statt JSON, ein JSON-Array oder String auf oberster Ebene oder generierte Eingabe mit sehr tiefer Verschachtelung. Auf den Header content-type kommt es nicht an, sondern auf den Body. Operationen: 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	Sende ein einzelnes JSON-Objekt als Body. Wenn die Eingabe generiert wird, prüfe ihre Verschachtelung.	Wird nicht wiederholt
missing_field	400	A required field is absent or empty.	Ein Feld, das die Operation verlangt, fehlt, ist null, leer oder kein String – oft ein anders geschriebener Name, etwa public_key statt publicKey. Operationen: 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	Ergänze das Feld, das die Meldung nennt; die Referenzseite der Operation listet die Pflichtfelder auf.	Wird nicht wiederholt
invalid_input	400	A field could not be parsed — the message explains exactly why.	Ein Feld ist vorhanden, lässt sich aber nicht parsen: ein Schlüssel, eine Signatur, ein Token oder ein Zertifikat in einer Kodierung oder einem Format, das die Operation nicht erkennt. Operationen: 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	Lies die Meldung – sie nennt das Feld und den Grund. Prüfe die Kodierung (Hex, base64, PEM) und bei Signaturen die Kurve.	Wird nicht wiederholt
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.	Eine ganze Schlüsseldatei, eingefügt, wo nur die öffentliche Hälfte gebraucht wird: ein PEM im Format PKCS#8 oder SEC1, ein privater Schlüssel im Format OpenSSH oder PuTTY, ein JWK, der noch „d“ hat – auch verschachtelt in einem String, der JSON enthält. Operationen: 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	Sende nur öffentliche Daten. Für die Arbeit mit einem privaten Schlüssel nutze die Browser-Tools – sie laufen auf deinem Rechner und senden nichts.	Wird nicht wiederholt
unsupported_algorithm	400	The token's algorithm is not one this operation verifies.	Ein JWT mit einem Algorithmus, den die Operation nicht prüft: HS, RS, PS*, EdDSA, ES256K oder none. Operationen: Verify an ES256/ES384/ES512 JWT signature	Diese API prüft ES256, ES384 und ES512. Prüfe andere Algorithmen lokal mit einer JWT-Bibliothek – ein HMAC-Secret darf nie irgendwohin gesendet werden.	Wird nicht wiederholt
invalid_domain	400	Not a public DNS hostname (IP addresses, single-label names and paths are refused).	Das Pfadsegment ist eine IP-Adresse, ein Name ohne Punkt wie localhost oder Text, der kein Hostname ist. Schema, Port oder Pfad rund um den Namen werden vorher entfernt. Operationen: TLS signature-health grade for a domain	Sende einen öffentlichen Hostnamen wie `github.com`. IP-Adressen und interne Namen lassen sich von hier aus nicht scannen.	Wird nicht wiederholt
scan_dns_error	400	The domain does not resolve in public DNS.	Der Name lässt sich im öffentlichen DNS nicht auflösen: Die Domain existiert nicht (ein Tippfehler, eine abgelaufene Registrierung, ein Name, den nur ein internes DNS kennt), es gibt keinen A- oder AAAA-Eintrag, oder es tritt ein DNS-Fehler auf. Operationen: TLS signature-health grade for a domain	Prüfe die Schreibweise und ob der Name A- oder AAAA-Einträge hat.	Wird nicht wiederholt
scan_private_address	400	The domain resolves (at least partly) to a private or reserved address.	Eine Adresse des Namens – IPv4, IPv6 oder in IPv6 eingebettetes IPv4 – liegt in einem privaten oder reservierten Bereich, etwa einem internen Netz oder Loopback. Eine Mischung aus öffentlichen und privaten Adressen wird als Ganzes abgewiesen. Operationen: TLS signature-health grade for a domain	Prüfe einen Host, der aus dem öffentlichen Internet erreichbar ist – interne Hosts lassen sich von hier aus nicht scannen.	Wird nicht wiederholt
webhook_url_refused mit API-Schlüsseln	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.	Anlegen eines Endpunkts mit einer http-URL, einem anderen Port als 443, einer IP-Adresse oder einem internen Namen oder mit einem Host, dessen DNS-Antwort eine private oder reservierte Adresse enthält – auch wenn das nur auf eine von mehreren Adressen zutrifft. Operationen: Create a webhook endpoint	Verwende eine https-URL auf dem Standardport mit einem öffentlichen Hostnamen. Die Meldung nennt die Regel, gegen die die URL verstößt, und bei einer abgewiesenen Adresse die Adresse und den Bereich.	Wird nicht wiederholt
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.	Ein Header `Authorization` oder `X-API-Key` ist vorhanden, aber fehlerhaft formatiert – und, sobald API-Schlüssel starten, ein Schlüssel, der unbekannt, widerrufen oder abgelaufen ist. Operationen: 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	Entferne den Header, um die API anonym aufzurufen, oder sende einen vollständigen, gültigen Schlüssel.	Wird nicht wiederholt
forbidden_scope mit API-Schlüsseln	403	The API key is valid but lacks a scope this operation requires; the message names it.	Ein Schlüssel, der ohne den Scope erstellt wurde, den eine Operation braucht – etwa ein Schlüssel, der nur den Scope api hat und die Operation des Domain-Checks aufruft, für die scan nötig ist. Operationen: 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	Verwende für den Aufruf einen Schlüssel mit diesem Scope.	Wird nicht wiederholt
webhook_limit_reached mit API-Schlüsseln	403	The account already has as many webhook endpoints as its plan allows.	Anlegen eines Endpunkts, obwohl das Konto schon so viele hat, wie sein Tarif erlaubt; der Free-Tarif erlaubt einen. Operationen: Create a webhook endpoint	Lösche einen Endpunkt, den du nicht mehr brauchst, oder lege den bestehenden mit derselben URL erneut an, um seine Beschreibung oder seine Ereignisse zu ändern.	Wird nicht wiederholt
not_found	404	No operation exists at this path.	Ein Pfad unter `/api/v1`, der keine Operation bezeichnet: ein Tippfehler, ein fehlendes oder ein überzähliges Segment. Kann bei jeder Operation auftreten.	Gleiche den Pfad mit der API-Referenz ab; Operationen liegen unter `/api/v1`.	Wird nicht wiederholt
webhook_not_found mit API-Schlüsseln	404	The API key's account has no webhook endpoint with this id.	Eine Endpunkt-ID, die nicht zum Konto des Schlüssels gehört: bereits gelöscht, vertippt oder die eines anderen Kontos. Operationen: Delete a webhook endpoint, Send a test event	Liste die Endpunkte des Kontos mit GET `/api/v1/webhooks` auf und verwende eine ID aus dieser Liste.	Wird nicht wiederholt
method_not_allowed	405	The path exists but does not accept this HTTP method; see the Allow header.	Aufruf einer POST-Operation mit GET – etwa durch Öffnen in der Adressleiste eines Browsers – oder umgekehrt. Kann bei jeder Operation auftreten.	Verwende eine Methode aus dem Header `Allow`: POST für Operationen mit JSON-Body, GET für die übrigen.	Wird nicht wiederholt
payload_too_large	413	The body exceeds 100 KB.	Der Body ist größer als 100 KB, meist weil ein ganzes Zertifikats-Bundle oder eine ganze Datei in ein Feld eingefügt wurde. Operationen: 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	Sende weniger pro Aufruf – eine Zertifikatskette, ein Token.	Wird nicht wiederholt
rate_limited	429	Too many requests — see Retry-After.	Zu viele Anfragen im aktuellen Zeitfenster: ohne Schlüssel pro IP, mit Schlüssel pro Schlüssel. Echte Scans einer Domain zehren außerdem von Budgets pro Host und insgesamt. Operationen: 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	Warte die Sekunden aus `Retry-After` ab, versuche es dann erneut und speichere Antworten auf deiner Seite zwischen.	Wird bis zu 2-mal wiederholt
quota_exceeded mit API-Schlüsseln	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.	Aufrufe mit einem Schlüssel haben die täglichen oder monatlichen Kontingenteinheiten des Kontos oder seine täglichen Domain-Scans aufgebraucht; Testschlüssel haben eigene, kleinere Kontingente. Operationen: 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	Versuche es nicht vor dem Zeitpunkt in `X-Quota-Reset` erneut: Erst dann beginnt das Kontingent von vorn, nicht früher.	Wird nicht wiederholt
internal_error	500	Unexpected server error.	Ein Fehler, mit dem die API nicht gerechnet hat. Er wird mit der Request-ID protokolliert – nie mit dem Body der Anfrage. Kann bei jeder Operation auftreten.	Bleibt der Fehler bestehen, melde die `requestId` aus dem Fehler-Body.	Wird nicht wiederholt
scan_unreachable	502	The domain refused or dropped the connection on port 443.	Der Name wird aufgelöst, aber aus dem Internet kommt keine TCP-Verbindung zu Port 443 zustande: kein HTTPS-Server, eine Firewall, die die Verbindung abweist oder verwirft, oder ein ausgefallener Host. Operationen: TLS signature-health grade for a domain	Prüfe, ob der Host für das öffentliche Internet HTTPS auf Port 443 bereitstellt.	Wird bis zu 2-mal wiederholt
scan_tls_error	502	The TLS handshake failed or presented no usable certificate.	Eine Verbindung auf Port 443 kommt zustande, aber der TLS-Handshake endet mit einem Alert oder scheitert an nicht zusammenpassenden Protokollen – oder der Server sendet kein Zertifikat, das der Scanner lesen kann. Operationen: TLS signature-health grade for a domain	Prüfe die TLS-Konfiguration des Servers, zum Beispiel mit dem Bericht des Domain-Checks.	Wird bis zu 2-mal wiederholt
service_unavailable mit API-Schlüsseln	503	API keys cannot be verified right now (the key store is unreachable); retry shortly.	Der Schlüsselspeicher ist nicht erreichbar, daher lässt sich ein mitgesendeter Schlüssel nicht prüfen. Ein Aufruf, der einen Schlüssel mitsendet, wird nie anonym beantwortet. Operationen: 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	Versuche es gleich noch einmal – das tun auch die SDKs.	Wird bis zu 2-mal wiederholt
webhooks_unavailable mit API-Schlüsseln	503	Webhooks are switched off on this server: it has no signing keys configured.	Auf dem Server sind keine Signaturschlüssel für Webhooks konfiguriert, daher kann er keine Zustellungen signieren; jede Webhook-Operation antwortet mit diesem Code, bis Schlüssel hinterlegt sind. Operationen: List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	An der Anfrage ist nichts zu ändern: Webhooks sind auf diesem Server vorerst abgeschaltet. Versuche es später noch einmal.	Wird bis zu 2-mal wiederholt
scan_timeout	504	The scan did not finish in time.	Namensauflösung, Verbindungsaufbau oder TLS-Handshake haben länger gedauert, als der Scanner erlaubt – ein langsamer oder überlasteter Host oder stillschweigend verworfene Pakete. Operationen: TLS signature-health grade for a domain	Versuche es später erneut; langsame oder überlastete Hosts können das Zeitbudget überschreiten.	Wird bis zu 2-mal wiederholt
timeout	504	The operation did not finish within its time budget.	Die Verarbeitung der Anfrage hat ihr Zeitbudget von 10 Sekunden überschritten. Bei Eingaben innerhalb der Anfragelimits ist das nicht zu erwarten. Operationen: 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	Versuche es einmal erneut; läuft dieselbe Eingabe wieder in einen Timeout, melde die `requestId` aus dem Fehler-Body.	Wird bis zu 2-mal wiederholt

Wiederholungen

Die offiziellen SDKs wiederholen Anfragen bei 429 (außer quota_exceeded), 502, 503 und 504 – höchstens 2-mal – und warten dabei so lange, wie Retry-After verlangt (höchstens 60 Sekunden), andernfalls nach exponentiellem Backoff mit Full Jitter. Jede Operation ist eine reine Funktion ihrer Eingabe, eine Wiederholung ist also immer sicher; dein eigener Client kann nach derselben Regel vorgehen.