Códigos de error

Una llamada fallida responde con un estado HTTP y un sobre JSON cuyo code indica cuál es el problema. Estos son los 25 códigos que puede enviar la API. Pueden aparecer códigos nuevos dentro de la v1: trata uno que no conozcas según su estado HTTP.

El sobre de error

Todos los cuerpos de error tienen esta forma; code y message siempre están presentes.

Campo	Tipo	Obligatorio	Descripción
error	object	sí
error.code	string	sí	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	sí	Human-readable explanation (English).
error.requestId	string	no	The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1.
error.detail	object	no	Structured context for the error, such as the offending field; omitted when there is none. cualquier nombre de miembro
error.docs	string	no	Where the error codes are explained. Sent since v1.1. formato uri

Una respuesta de error real (la solicitud omite el campo obligatorio):

curl

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

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

Todos los códigos

Código	HTTP	Significado	Cuándo se produce	Qué hacer	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.	Causas habituales: un cuerpo codificado como formulario o en texto plano en lugar de JSON, un array o una cadena JSON en el nivel superior, o una entrada generada con un anidamiento muy profundo. El encabezado content-type no importa; lo que cuenta es el cuerpo. Operaciones: 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	Envía un único objeto JSON como cuerpo. Si la entrada se genera automáticamente, comprueba su anidamiento.	No se reintenta
missing_field	400	A required field is absent or empty.	Un campo que la operación requiere falta, es null, está vacío o no es una cadena; a menudo, porque el nombre está escrito de otra forma, como public_key en lugar de publicKey. Operaciones: 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	Añade el campo que indica el mensaje; la página de referencia de la operación enumera los campos obligatorios.	No se reintenta
invalid_input	400	A field could not be parsed — the message explains exactly why.	Un campo está presente, pero no se puede analizar: una clave, una firma, un token o un certificado en una codificación o un formato que la operación no reconoce. Operaciones: 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	Lee el mensaje: indica el campo y el motivo. Comprueba la codificación (hex, base64, PEM) y, en el caso de las firmas, la curva.	No se reintenta
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 archivo de clave completo pegado donde solo hace falta la mitad pública: un PEM PKCS#8 o SEC1, una clave privada de OpenSSH o PuTTY, una JWK que aún lleva «d»; también cuando va anidado dentro de una cadena que contiene JSON. Operaciones: 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	Envía solo datos públicos. Para trabajar con una clave privada, usa las herramientas del navegador: se ejecutan en tu equipo y no envían nada.	No se reintenta
unsupported_algorithm	400	The token's algorithm is not one this operation verifies.	Un JWT con un algoritmo que la operación no verifica: HS, RS, PS*, EdDSA, ES256K o none. Operaciones: Verify an ES256/ES384/ES512 JWT signature	Esta API verifica ES256, ES384 y ES512. Comprueba otros algoritmos localmente con una biblioteca de JWT: un secreto HMAC no debe enviarse nunca a ninguna parte.	No se reintenta
invalid_domain	400	Not a public DNS hostname (IP addresses, single-label names and paths are refused).	El segmento de la ruta es una dirección IP, un nombre sin punto como localhost o un texto que no es un nombre de host. Primero se eliminan el esquema, el puerto o la ruta que acompañen al nombre. Operaciones: TLS signature-health grade for a domain	Envía un nombre de host público, como `github.com`. Las direcciones IP y los nombres internos no se pueden escanear desde aquí.	No se reintenta
scan_dns_error	400	The domain does not resolve in public DNS.	La resolución del nombre en el DNS público falla: el dominio no existe (una errata, un registro de dominio caducado, un nombre que solo conoce un DNS interno), no hay registro A ni AAAA, o se produce un fallo de DNS. Operaciones: TLS signature-health grade for a domain	Comprueba la ortografía y que el nombre tenga registros A o AAAA.	No se reintenta
scan_private_address	400	The domain resolves (at least partly) to a private or reserved address.	Una dirección del nombre —IPv4, IPv6 o IPv4 incrustada en IPv6— está en un rango privado o reservado, como el de una red interna o el de loopback. Una mezcla de direcciones públicas y privadas se rechaza en su totalidad. Operaciones: TLS signature-health grade for a domain	Comprueba un host accesible públicamente desde internet: los hosts internos no se pueden escanear desde aquí.	No se reintenta
webhook_url_refused con claves de 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.	Crear un endpoint con una URL http, un puerto distinto de 443, una dirección IP o un nombre interno, o un host cuya respuesta DNS incluye una dirección privada o reservada, también cuando solo lo es una de varias direcciones. Operaciones: Create a webhook endpoint	Usa una URL https en el puerto predeterminado con un nombre de host público. El mensaje indica qué regla incumple la URL y, si se rechaza una dirección, qué dirección y qué rango.	No se reintenta
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.	Hay un encabezado `Authorization` o `X-API-Key`, pero está mal formado; y, cuando lleguen las claves de API, también una clave desconocida, revocada o caducada. Operaciones: 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	Quita el encabezado para llamar de forma anónima o envía una clave completa y válida.	No se reintenta
forbidden_scope con claves de API	403	The API key is valid but lacks a scope this operation requires; the message names it.	Una clave creada sin el ámbito que necesita una operación; por ejemplo, una clave que solo tiene el ámbito api y llama a la operación de diagnóstico de dominios, que necesita scan. Operaciones: 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	Llama con una clave que tenga ese ámbito.	No se reintenta
webhook_limit_reached con claves de API	403	The account already has as many webhook endpoints as its plan allows.	Crear un endpoint cuando la cuenta ya tiene tantos como permite su plan; el plan gratuito permite uno. Operaciones: Create a webhook endpoint	Elimina un endpoint que ya no necesites o vuelve a crear el existente con la misma URL para cambiar su descripción o sus eventos.	No se reintenta
not_found	404	No operation exists at this path.	Una ruta bajo `/api/v1` que no corresponde a ninguna operación: una errata, un segmento que falta o uno que sobra. Cualquier operación puede devolverlo.	Compara la ruta con la referencia de la API; las operaciones están bajo `/api/v1`.	No se reintenta
webhook_not_found con claves de API	404	The API key's account has no webhook endpoint with this id.	Un ID de endpoint que no pertenece a la cuenta de la clave: ya eliminado, mal escrito o de otra cuenta. Operaciones: Delete a webhook endpoint, Send a test event	Obtén la lista de endpoints de la cuenta con GET `/api/v1/webhooks` y usa un ID de esa lista.	No se reintenta
method_not_allowed	405	The path exists but does not accept this HTTP method; see the Allow header.	Llamar con GET a una operación POST (por ejemplo, al abrirla en la barra de direcciones de un navegador) o al revés. Cualquier operación puede devolverlo.	Usa un método del encabezado `Allow`: POST para las operaciones que reciben un cuerpo JSON y GET para las demás.	No se reintenta
payload_too_large	413	The body exceeds 100 KB.	El cuerpo supera los 100 KB, normalmente por pegar en un solo campo todo un paquete de certificados o un archivo entero. Operaciones: 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	Envía menos en cada llamada: una cadena de certificados, un token.	No se reintenta
rate_limited	429	Too many requests — see Retry-After.	Demasiadas solicitudes en la ventana actual: por IP sin clave, por clave si la hay. Los escaneos reales de un dominio también consumen cupos por host y globales. Operaciones: 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	Espera los segundos que indica `Retry-After`, reintenta después y guarda las respuestas en caché por tu parte.	Se reintenta hasta 2 veces
quota_exceeded con claves de 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.	Las llamadas hechas con una clave agotan las unidades de cuota diarias o mensuales de la cuenta, o sus escaneos de dominio diarios; las claves de prueba tienen sus propias cuotas, más pequeñas. Operaciones: 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	No reintentes antes de la hora indicada en `X-Quota-Reset`: la cuota se renueva entonces, no antes.	No se reintenta
internal_error	500	Unexpected server error.	Un fallo que la API no previó. Se registra con el ID de solicitud, nunca con el cuerpo de la solicitud. Cualquier operación puede devolverlo.	Si persiste, notifícalo con el `requestId` del cuerpo del error.	No se reintenta
scan_unreachable	502	The domain refused or dropped the connection on port 443.	El nombre se resuelve, pero ninguna conexión TCP al puerto 443 se completa desde internet: no hay servidor HTTPS, un cortafuegos la rechaza o la descarta, o el host está caído. Operaciones: TLS signature-health grade for a domain	Comprueba que el host sirva HTTPS en el puerto 443 y sea accesible públicamente desde internet.	Se reintenta hasta 2 veces
scan_tls_error	502	The TLS handshake failed or presented no usable certificate.	Se abre una conexión en el puerto 443, pero el handshake TLS termina con una alerta o una incompatibilidad de protocolo, o el servidor no envía ningún certificado que el escáner pueda leer. Operaciones: TLS signature-health grade for a domain	Revisa la configuración TLS del servidor, por ejemplo con el informe de diagnóstico del dominio.	Se reintenta hasta 2 veces
service_unavailable con claves de API	503	API keys cannot be verified right now (the key store is unreachable); retry shortly.	No se puede acceder al almacén de claves, así que no se puede comprobar una clave presentada. Una llamada que presenta una clave nunca se atiende de forma anónima. Operaciones: 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	Reintenta en breve: los SDK lo hacen.	Se reintenta hasta 2 veces
webhooks_unavailable con claves de API	503	Webhooks are switched off on this server: it has no signing keys configured.	El servidor no tiene configuradas claves de firma de webhooks, así que no puede firmar las entregas; todas las operaciones de webhooks responden con este código hasta que se configuren las claves. Operaciones: List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	No hay nada que cambiar en la solicitud: los webhooks están desactivados en este servidor por ahora. Vuelve a intentarlo más tarde.	Se reintenta hasta 2 veces
scan_timeout	504	The scan did not finish in time.	La resolución del nombre, la conexión o el handshake TLS tardan más de lo que permite el escáner: un host lento o sobrecargado, o paquetes descartados sin aviso. Operaciones: TLS signature-health grade for a domain	Reintenta más tarde; los hosts lentos o sobrecargados pueden superar el tiempo disponible.	Se reintenta hasta 2 veces
timeout	504	The operation did not finish within its time budget.	El procesamiento de la solicitud superó su límite de tiempo de 10 segundos. No se espera que eso ocurra con una entrada dentro de los límites de la solicitud. Operaciones: 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	Reintenta una vez; si la misma entrada vuelve a agotar el tiempo, notifícalo con el `requestId` del cuerpo del error.	Se reintenta hasta 2 veces

Reintentos

Los SDK oficiales reintentan las respuestas 429 (excepto quota_exceeded), 502, 503 y 504 —como máximo 2 veces— y esperan el tiempo que indique Retry-After (como máximo 60 segundos) o, si no lo indica, aplican retroceso exponencial con jitter completo. Cada operación es una función pura de su entrada, así que un reintento siempre es seguro; tu propio cliente puede seguir la misma regla.