> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência de Códigos de Erro

> 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.

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

| Veredito | Saída da CLI | Descrição |
| - | - | - |
| VALID | 0 | Atestação verificada com sucesso |
| ALTERED | 10 | O hash da carga não corresponde |
| REVOKED | 11 | A atestação foi revogada |
| KEY\_COMPROMISED | 12 | Chave de assinatura marcada como comprometida |
| KEY\_EXPIRED | 13 | A chave de assinatura expirou |
| LOG\_PROOF\_FAILED | 14 | A verificação da prova do log de transparência falhou |
| SIGNATURE\_INVALID | 15 | A verificação da assinatura criptográfica falhou |

### Razões de verificação

Ao chamar o [endpoint Verify](https://docs.truthlocks.com/pt/api-reference/verify.md), a resposta inclui um array `reasons` com contexto adicional. Esses códigos de razão são informativos e aparecem junto com o veredito:

| Razão | Veredito | Descrição |
| :- | :- | :- |
| `document_hash_mismatch` | `ALTERED` | O `document_hash_hex` fornecido não corresponde ao hash armazenado no momento da cunhagem |
| `document_hash_not_stored` | (qualquer) | A atestação foi cunhada sem um hash de documento, então a verificação de hash de documento foi ignorada |

## Códigos de erro da API

### Geral

| Código | HTTP | Descrição |
| :- | :- | :- |
| `INVALID_INPUT` | 400 | A validação da solicitação falhou |
| `INVALID_REQUEST` | 400 | O corpo da solicitação ou os parâmetros estão malformados |
| `INVALID_ID` | 400 | O identificador não é um UUID válido |
| `NOT_FOUND` | 404 | Recurso não encontrado |
| `UNAUTHORIZED` | 401 | Autenticação necessária |
| `FORBIDDEN` | 403 | Permissão negada |
| `CONFLICT` | 409 | Conflito de estado de recurso |
| `INTERNAL_ERROR` | 500 | Ocorreu um erro inesperado no servidor |
| `DB_ERROR` | 500 | Uma operação de banco de dados falhou |

### Atestados e emissores

| Código | HTTP | Descrição |
| :- | :- | :- |
| `ISSUER_NOT_TRUSTED` | 403 | O emissor deve estar no status `trusted` para cunhar atestados |
| `KEY_INACTIVE` | 400 | A chave de assinatura não está ativa |

### Chaves de API

| Código | HTTP | Descrição |
| :- | :- | :- |
| `NAME_REQUIRED` | 400 | É necessário um nome de chave |
| `KEY_ID_REQUIRED` | 400 | O parâmetro Key ID está faltando |
| `KEY_NOT_FOUND` | 404 | Chave de API não encontrada |
| `KEY_LIMIT` | 409 | Número máximo de chaves de API ativas atingido (5 por consumidor) |

### Consumidor

| Código | HTTP | Descrição |
| :- | :- | :- |
| `CONSUMER_REQUIRED` | 400 | É necessária uma referência de e-mail do consumidor |

### Identidade e DID

| Código | HTTP | Descrição |
| :- | :- | :- |
| `MISSING_DID` | 400 | O parâmetro DID é obrigatório |
| `DID_NOT_FOUND` | 404 | DID não encontrado ou o emissor associado foi revogado |
| `MISSING_ID` | 400 | O parâmetro Issuer ID é obrigatório |
| `EMAIL_NOT_VERIFIED` | 403 | O endereço de e-mail não foi verificado |

### SSO

| Código | HTTP | Descrição |
| :- | :- | :- |
| `DISCOVERY_FAILED` | 400 | A configuração de descoberta OIDC não pôde ser carregada |
| `METADATA_FETCH_FAILED` | 400 | Os metadados do SAML IdP não puderam ser obtidos |
| `CRYPTO_ERROR` | 500 | Uma operação de criptografia falhou |
| `TEST_FAILED` | 400 | O teste de conexão SSO não foi bem-sucedido |
| `AUTH_FAILED` | 401 | A autenticação SSO falhou |
| `INVALID_STATE` | 401 | O parâmetro de estado OAuth ou SAML é inválido |
| `EXPIRED_SESSION` | 401 | A sessão de login SSO expirou |
| `REPLAY_DETECTED` | 401 | O token de estado OAuth ou SAML já foi usado |
| `CONFIG_ERROR` | 500 | A configuração SSO está ausente ou inválida |

### Política e governança

| Código | HTTP | Descrição |
| :- | :- | :- |
| `POLICY_VIOLATION` | 403 | A solicitação viola uma política ativa |

### Faturamento e limites

| Código | HTTP | Descrição |
| :- | :- | :- |
| `BILLING_LIMIT` | 402 | Cota de faturamento esgotada para o ciclo atual |
| `LIMIT_REACHED` | 429 | Limite de proteção mensal atingido |
| `SEAT_LIMIT` | 402 | Limite de assentos da equipe atingido — atualize seu plano ou remova um membro existente |

### Residência de dados

| Código | HTTP | Descrição |
| :- | :- | :- |
| `REGION_MISMATCH` | 409 | O inquilino está fixado em uma região diferente daquela que processa a solicitação |

## 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](https://docs.truthlocks.com/pt/sdk/go.md) quando `MaxRetries` (ou equivalente) está configurado:

| Status HTTP | Código | Quando tentar novamente |
| :- | :- | :- |
| `408` | Tempo limite da requisição | Imediatamente — o servidor não recebeu a requisição a tempo |
| `429` | `RATE_LIMITED` | Após a duração especificada no cabeçalho `Retry-After` |
| `500` | `INTERNAL_ERROR` | Com backoff exponencial — problema transitório do servidor |
| `502` | Bad Gateway | Com backoff exponencial — serviço a montante indisponível |
| `503` | Serviço Indisponível | Com backoff exponencial — serviço temporariamente sobrecarregado |
| `504` | Gateway Timeout | Com backoff exponencial — o serviço a montante excedeu o tempo limite |

### Terminal (não tentar novamente)

Esses erros indicam um problema com a solicitação que não será resolvido com a repetição:

| Status HTTP | Códigos de exemplo | Ação |
| :- | :- | :- |
| `400` | `INVALID_INPUT`, `INVALID_REQUEST` | Corrija a carga da solicitação |
| `401` | `UNAUTHORIZED` | Verifique sua chave de API ou token de autenticação |
| `403` | `FORBIDDEN`, `ISSUER_NOT_TRUSTED`, `POLICY_VIOLATION` | Verifique as permissões ou o status do emissor |
| `404` | `NOT_FOUND` | Verifique se o ID do recurso existe |
| `409` | `CONFLICT` | Resolva o conflito de estado antes de tentar novamente |

> [!TIP]
>
> 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:

```json theme={null}
{
  "code": "ISSUER_NOT_TRUSTED",
  "message": "Issuer must be in trusted status to mint attestations"
}
```

* **`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.

> [!NOTE]
>
> 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](https://www.rfc-editor.org/rfc/rfc7807). 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:

```json theme={null}
{
  "type": "https://docs.truthlocks.com/ops/errors",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested path does not match any API route."
}
```

| Campo | Descrição |
| :- | :- |
| `type` | Uma referência URI que identifica o tipo de erro. Aponta para esta página de documentação. |
| `title` | Um breve resumo do erro. Ou `Not Found` ou `Method Not Allowed`. |
| `status` | O código de status HTTP — `404` ou `405`. |
| `detail` | Uma explicação legível por humanos do erro específico. |

### 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](https://docs.truthlocks.com/pt/api-reference/attestations/mint.md) 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`.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/nonexistent");
const contentType = res.headers.get("content-type");

if (contentType?.includes("application/problem+json")) {
  // Gateway error — RFC 7807 format
  const problem = await res.json();
  console.error(`${problem.status} ${problem.title}: ${problem.detail}`);
} else {
  // Application error — standard format
  const error = await res.json();
  console.error(`${error.code}: ${error.message}`);
}
```

> [!TIP]
>
> Os [SDKs](https://docs.truthlocks.com/pt/sdk/js.md) 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

> [card] Algoritmo
>
> \* `Ed25519` \* `ES256` \* `ES384` \* `ES512` \* `RS256` \* `RS384` \* `RS512` \* `PS256` \* `PS384` \* `PS512`

> [card] Status do Emissor
>
> * `pending` \* `trusted` \* `suspended` \* `revoked`

> [card] Nível de Confiança
>
> * `self_issued` \* `verified_org` \* `regulated_issuer`

> [card] Status da Chave
>
> * `ACTIVE` \* `DISABLED` \* `EXPIRED` \* `COMPROMISED`

> [card] Status da Atestação
>
> \* `ACTIVE` \* `REVOKED` \* `SUPERSEDED`

> [card] Classificação de Risco
>
> * `unknown` \* `low` \* `medium` \* `high` \* `critical`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.