Saltar para o conteúdo principal
Códigos de erro canônicos e vereditos usados em toda a plataforma Truthlocks. Esses códigos são estáveis e podem ser usados para tratamento programático de erros.

Vereditos de Verificação

Razões de verificação

Ao chamar o endpoint Verify, a resposta inclui um array reasons com contexto adicional. Esses códigos de razão são informativos e aparecem junto com o veredito:

Códigos de erro da API

Geral

Atestados e emissores

Chaves de API

Consumidor

Identidade e DID

SSO

Política e governança

Faturamento e limites

Residência de dados

Erros passíveis de nova tentativa vs. erros terminais

Ao decidir se deve tentar novamente uma requisição falha, use o código de status HTTP para determinar se o erro é transitório ou permanente.

Retentável (transitório)

Esses erros são automaticamente repetidos pelos SDKs quando MaxRetries (ou equivalente) está configurado:

Terminal (não tentar novamente)

Esses erros indicam um problema com a solicitação que não será resolvido com a repetição:
Todos os três SDKs lidam com erros passíveis de nova tentativa automaticamente com backoff exponencial e jitter. Você só precisa de lógica de nova tentativa manual se desativou as novas tentativas automáticas ou deseja um comportamento personalizado além dos padrões do SDK.

Formato de resposta de erro

Toda resposta de erro retorna um objeto JSON com dois campos:
  • code — um código de erro estável e legível por máquina das tabelas acima. Use-o para tratamento programático de erros.
  • message — uma descrição legível por humanos do que deu errado. As mensagens podem mudar entre as versões; não as use programaticamente.
Mensagens de erro que exporiam detalhes da infraestrutura (como strings de conexão de banco de dados ou nomes de host internos) são automaticamente substituídas por uma mensagem genérica antes de serem retornadas ao cliente. Os detalhes originais são registrados apenas no lado do servidor.

Erros de gateway (RFC 7807)

Quando uma requisição atinge o gateway da API, mas não corresponde a nenhuma rota válida, o gateway retorna uma resposta de erro estruturada seguindo a especificação RFC 7807 Problem Details. Isso se aplica a erros 404 Not Found e 405 Method Not Allowed no nível do gateway.

Formato de resposta

Os erros de gateway usam application/problem+json como tipo de conteúdo e incluem quatro campos:

Quando você vir esses erros

  • 404 Not Found — O caminho da solicitação não corresponde a nenhuma rota da API. Verifique novamente o URL, incluindo o prefixo de versão /v1/ e o nome do recurso.
  • 405 Method Not Allowed — O caminho da solicitação existe, mas o método HTTP que você usou (por exemplo, DELETE em um endpoint somente leitura) não é suportado. Verifique a referência da API para o método correto.

Lidar com erros de gateway no código

Se você analisar respostas de erro programaticamente, verifique o cabeçalho Content-Type para distinguir erros de gateway de erros de aplicativo:
  • application/problem+json — Erro em nível de gateway (RFC 7807). Use os campos status e title.
  • application/json — Erro em nível de aplicativo. Use os campos code e message.
Os SDKs do Truthlocks lidam com ambos os formatos de erro automaticamente. Você só precisa distingui-los se estiver chamando a API diretamente.

Enumerações Canônicas

Algoritmo

* Ed25519 * ES256 * ES384 * ES512 * RS256 * RS384 * RS512 * PS256 * PS384 * PS512

Status do Emissor

  • pending * trusted * suspended * revoked

Nível de Confiança

  • self_issued * verified_org * regulated_issuer

Status da Chave

  • ACTIVE * DISABLED * EXPIRED * COMPROMISED

Status da Atestação

* ACTIVE * REVOKED * SUPERSEDED

Classificação de Risco

  • unknown * low * medium * high * critical