Códigos de erro

Uma chamada com falha responde com um status HTTP e um envelope JSON cujo campo code diz o que deu errado. Estes são todos os 25 códigos que a API pode enviar. Novos códigos podem surgir dentro da v1: trate um código desconhecido pelo seu status HTTP.

O envelope de erro

Todo corpo de erro tem este formato; code e message estão sempre presentes.

Campo	Tipo	Obrigatório	Descrição
error	object	sim
error.code	string	sim	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	sim	Human-readable explanation (English).
error.requestId	string	não	The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1.
error.detail	object	não	Structured context for the error, such as the offending field; omitted when there is none. quaisquer nomes de membros
error.docs	string	não	Where the error codes are explained. Sent since v1.1. formato uri

Uma resposta de erro real — a requisição omite o campo obrigatório:

curl

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

Resposta 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 os códigos

Código	HTTP	Significado	Quando ocorre	O que fazer	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.	Causas típicas: um corpo codificado como formulário ou em texto puro em vez de JSON, um array ou uma string JSON no nível superior, ou uma entrada gerada com aninhamento muito profundo. O cabeçalho content-type não importa; o que importa é o corpo. Operações: 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	Envie um único objeto JSON como corpo. Se a entrada for gerada, verifique o aninhamento.	Sem novas tentativas
missing_field	400	A required field is absent or empty.	Um campo exigido pela operação está ausente, é nulo, está vazio ou não é uma string — muitas vezes um nome escrito de outro jeito, como public_key em vez de publicKey. Operações: 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	Adicione o campo indicado na mensagem; a página de referência da operação lista os campos obrigatórios.	Sem novas tentativas
invalid_input	400	A field could not be parsed — the message explains exactly why.	Um campo está presente, mas não pode ser interpretado: uma chave, assinatura, token ou certificado em uma codificação ou formato que a operação não reconhece. Operações: 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	Leia a mensagem — ela indica o campo e o motivo. Verifique a codificação (hex, base64, PEM) e, no caso de assinaturas, a curva.	Sem novas tentativas
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.	Um arquivo de chave inteiro colado onde só a metade pública é necessária: um PEM PKCS#8 ou SEC1, uma chave privada OpenSSH ou PuTTY, uma JWK que ainda traz “d” — inclusive aninhada dentro de uma string que contém JSON. Operações: 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	Envie apenas dados públicos. Para trabalhar com uma chave privada, use as ferramentas no navegador — elas rodam na sua máquina e não enviam nada.	Sem novas tentativas
unsupported_algorithm	400	The token's algorithm is not one this operation verifies.	Um JWT com um algoritmo que a operação não verifica: HS, RS, PS*, EdDSA, ES256K ou none. Operações: Verify an ES256/ES384/ES512 JWT signature	Esta API verifica ES256, ES384 e ES512. Verifique outros algoritmos localmente com uma biblioteca de JWT — um segredo HMAC nunca deve ser enviado a lugar nenhum.	Sem novas tentativas
invalid_domain	400	Not a public DNS hostname (IP addresses, single-label names and paths are refused).	O segmento do caminho é um endereço IP, um nome sem ponto como localhost ou um texto que não é um nome de host. Esquema, porta ou caminho em volta do nome são removidos antes. Operações: TLS signature-health grade for a domain	Envie um nome de host público, como `github.com`. Não é possível fazer varredura de endereços IP e nomes internos a partir daqui.	Sem novas tentativas
scan_dns_error	400	The domain does not resolve in public DNS.	A resolução do nome no DNS público falha: o domínio não existe (um erro de digitação, um registro de domínio expirado, um nome que só um DNS interno conhece), não há registro A ou AAAA, ou houve uma falha de DNS. Operações: TLS signature-health grade for a domain	Verifique a grafia e se o nome tem registros A ou AAAA.	Sem novas tentativas
scan_private_address	400	The domain resolves (at least partly) to a private or reserved address.	Um dos endereços do nome — IPv4, IPv6 ou IPv4 embutido em IPv6 — está em uma faixa privada ou reservada, como uma rede interna ou loopback. Uma mistura de endereços públicos e privados é recusada por inteiro. Operações: TLS signature-health grade for a domain	Verifique um host acessível pela internet pública — não é possível fazer varredura de hosts internos a partir daqui.	Sem novas tentativas
webhook_url_refused com chaves 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.	Criar um endpoint com uma URL http, uma porta diferente de 443, um endereço IP ou um nome interno, ou um host cuja resposta de DNS inclui um endereço privado ou reservado — mesmo quando só um entre vários endereços é privado ou reservado. Operações: Create a webhook endpoint	Use uma URL https na porta padrão com um nome de host público. A mensagem diz qual regra a URL violou e, no caso de um endereço recusado, qual endereço e qual faixa.	Sem novas tentativas
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.	Um cabeçalho `Authorization` ou `X-API-Key` está presente, mas malformado — e, quando as chaves de API forem lançadas, uma chave desconhecida, revogada ou expirada. Operações: 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	Remova o cabeçalho para chamar de forma anônima ou envie uma chave completa e válida.	Sem novas tentativas
forbidden_scope com chaves de API	403	The API key is valid but lacks a scope this operation requires; the message names it.	Uma chave criada sem o escopo de que uma operação precisa, como uma chave só com o escopo api chamando a operação de health check de domínio, que exige o escopo scan. Operações: 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	Chame com uma chave que tenha esse escopo.	Sem novas tentativas
webhook_limit_reached com chaves de API	403	The account already has as many webhook endpoints as its plan allows.	Criar um endpoint quando a conta já tem tantos quanto o plano permite; o plano gratuito permite um. Operações: Create a webhook endpoint	Exclua um endpoint de que você não precisa mais ou crie de novo o endpoint existente com a mesma URL para alterar a descrição ou os eventos.	Sem novas tentativas
not_found	404	No operation exists at this path.	Um caminho em `/api/v1` que não corresponde a nenhuma operação: um erro de digitação, um segmento faltando ou sobrando. Qualquer operação pode responder com ele.	Confira o caminho na referência da API; as operações ficam em `/api/v1`.	Sem novas tentativas
webhook_not_found com chaves de API	404	The API key's account has no webhook endpoint with this id.	Um ID de endpoint que não pertence à conta da chave: já excluído, digitado errado ou de outra conta. Operações: Delete a webhook endpoint, Send a test event	Liste os endpoints da conta com GET `/api/v1/webhooks` e use um ID dessa lista.	Sem novas tentativas
method_not_allowed	405	The path exists but does not accept this HTTP method; see the Allow header.	Chamar uma operação POST com GET — abrindo-a na barra de endereços do navegador, por exemplo — ou o contrário. Qualquer operação pode responder com ele.	Use um método do cabeçalho `Allow`: POST para operações que recebem um corpo JSON, GET para as demais.	Sem novas tentativas
payload_too_large	413	The body exceeds 100 KB.	O corpo tem mais de 100 KB, geralmente porque um pacote inteiro de certificados ou um arquivo inteiro foi colado em um campo. Operações: 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	Envie menos por chamada — uma cadeia de certificados, um token.	Sem novas tentativas
rate_limited	429	Too many requests — see Retry-After.	Requisições demais na janela atual: por IP sem chave, por chave com uma. As varreduras reais de um domínio também consomem cotas por host e globais. Operações: 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	Espere os segundos indicados em `Retry-After`, tente de novo e mantenha as respostas em cache do seu lado.	Até 2 novas tentativas
quota_exceeded com chaves 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.	As chamadas feitas com uma chave esgotaram as unidades de cota diárias ou mensais da conta ou as varreduras diárias de domínio; chaves de teste têm cotas próprias, menores. Operações: 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	Não tente de novo antes do horário indicado em `X-Quota-Reset`: a cota recomeça nesse momento, não antes.	Sem novas tentativas
internal_error	500	Unexpected server error.	Uma falha que a API não previu. Ela é registrada em log com o ID da requisição — nunca com o corpo da requisição. Qualquer operação pode responder com ele.	Se persistir, informe o `requestId` do corpo do erro.	Sem novas tentativas
scan_unreachable	502	The domain refused or dropped the connection on port 443.	O nome é resolvido, mas nenhuma conexão TCP na porta 443 é bem-sucedida a partir da internet: não há servidor HTTPS, um firewall recusa ou descarta a conexão, ou o host está fora do ar. Operações: TLS signature-health grade for a domain	Verifique se o host atende HTTPS na porta 443 para a internet pública.	Até 2 novas tentativas
scan_tls_error	502	The TLS handshake failed or presented no usable certificate.	Uma conexão na porta 443 é aberta, mas o handshake TLS termina com um alerta ou uma incompatibilidade de protocolo, ou o servidor não envia nenhum certificado que o scanner consiga ler. Operações: TLS signature-health grade for a domain	Verifique a configuração TLS do servidor, por exemplo, com o relatório de health check do domínio.	Até 2 novas tentativas
service_unavailable com chaves de API	503	API keys cannot be verified right now (the key store is unreachable); retry shortly.	O armazenamento de chaves está inacessível, então uma chave apresentada não pode ser verificada. Uma chamada que apresenta uma chave nunca é atendida de forma anônima. Operações: 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	Tente de novo em instantes — os SDKs fazem isso.	Até 2 novas tentativas
webhooks_unavailable com chaves de API	503	Webhooks are switched off on this server: it has no signing keys configured.	O servidor não tem chaves de assinatura de webhook configuradas, então não consegue assinar as entregas; toda operação de webhook responde com este código até que as chaves sejam configuradas. Operações: List webhook endpoints, Create a webhook endpoint, Delete a webhook endpoint, Send a test event	Não há nada a mudar na requisição: os webhooks estão desativados neste servidor por enquanto. Tente de novo mais tarde.	Até 2 novas tentativas
scan_timeout	504	The scan did not finish in time.	A resolução do nome, a conexão ou o handshake TLS levou mais tempo do que o scanner permite — um host lento ou sobrecarregado, ou pacotes descartados silenciosamente. Operações: TLS signature-health grade for a domain	Tente de novo mais tarde; hosts lentos ou sobrecarregados podem exceder o limite de tempo.	Até 2 novas tentativas
timeout	504	The operation did not finish within its time budget.	O processamento da requisição ultrapassou o limite de tempo de 10 segundos. Não se espera que isso aconteça com uma entrada dentro dos limites de requisição. Operações: 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	Tente de novo uma vez; se a mesma entrada estourar o tempo outra vez, informe o `requestId` do corpo do erro.	Até 2 novas tentativas

Novas tentativas

Os SDKs oficiais tentam de novo em caso de 429 (exceto quota_exceeded), 502, 503 e 504 — no máximo 2 vezes —, esperando o tempo que Retry-After pedir (no máximo 60 segundos) ou, sem esse cabeçalho, com backoff exponencial e jitter completo. Toda operação é uma função pura da entrada, então uma nova tentativa é sempre segura; seu próprio cliente pode seguir a mesma regra.