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

# Erros

> Códigos de erro que você pode encontrar e como tratá-los.

Erros seguem [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) e são
servidos com `Content-Type: application/problem+json`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json

{
  "type":     "https://errors.attestly.io/quota-exceeded",
  "title":    "Quota Exceeded",
  "status":   429,
  "detail":   "Monthly quota of 10000 requests exceeded for this billing period.",
  "instance": "/v1/evaluate",
  "quota": {
    "limit": 10000,
    "used":  10000,
    "period_started_at": "2026-04-15T00:00:00Z",
    "period_ends_at":   "2026-05-15T00:00:00Z"
  }
}
```

Faça match pela URI em `type` — ela é estável entre releases e
dereferenciável para documentação. `title` e `detail` são para
humanos e podem ser reescritos; não programe em cima deles.

Alguns tipos carregam **extension members** (o bloco `quota` acima é
um deles). Os membros base (`type`, `title`, `status`, `detail`,
`instance`) sempre vêm; extensions são documentadas por tipo de erro
abaixo.

## Autenticação & acesso

| Status | Type URI                                           | Quando                                                |
| ------ | -------------------------------------------------- | ----------------------------------------------------- |
| 401    | `https://errors.attestly.io/authentication-failed` | API key ausente, malformada ou revogada.              |
| 402    | `https://errors.attestly.io/subscription-inactive` | Subscription não está mais ativa.                     |
| 429    | `https://errors.attestly.io/quota-exceeded`        | Teto mensal atingido para o período de billing atual. |
| 429    | `https://errors.attestly.io/rate-limit-exceeded`   | Muitas requests em uma janela curta.                  |

Respostas 429 carregam headers `Retry-After` e `X-RateLimit-*`. O
tipo `quota-exceeded` carrega adicionalmente uma extension `quota`
com `limit`, `used`, `period_started_at`, `period_ends_at`. Veja
[Quotas](/pt-BR/reference/quotas).

## Validação

| Status | Type URI                                                | Quando                                                        |
| ------ | ------------------------------------------------------- | ------------------------------------------------------------- |
| 422    | `https://errors.attestly.io/request-validation-failed`  | JSON malformado, tipos errados, campos obrigatórios faltando. |
| 422    | `https://errors.attestly.io/program-validation-failed`  | Estrutura do ruleset inválida (depth, refs, limites).         |
| 422    | `https://errors.attestly.io/program-compilation-failed` | Referências do ruleset não puderam ser compiladas.            |
| 422    | `https://errors.attestly.io/unknown-source`             | Ruleset referencia source que você não pode acessar.          |

## Catálogo

| Status | Type URI                                            | Quando                            |
| ------ | --------------------------------------------------- | --------------------------------- |
| 404    | `https://errors.attestly.io/ruleset-not-found`      | `ruleset_id` não resolve.         |
| 409    | `https://errors.attestly.io/ruleset-already-exists` | `(name, version)` já está em uso. |

## Idempotência

| Status | Type URI                                                | Quando                                          |
| ------ | ------------------------------------------------------- | ----------------------------------------------- |
| 422    | `https://errors.attestly.io/idempotency-key-invalid`    | Header `Idempotency-Key` malformado.            |
| 422    | `https://errors.attestly.io/idempotency-key-conflict`   | Mesma chave, body diferente.                    |
| 429    | `https://errors.attestly.io/idempotency-key-exhausted`  | Muitas requests concorrentes com a mesma chave. |
| 410    | `https://errors.attestly.io/idempotency-replay-expired` | A janela de replay para essa chave expirou.     |

## Servidor (5xx)

| Status | Type URI                                          | Quando                                 |
| ------ | ------------------------------------------------- | -------------------------------------- |
| 500    | `https://errors.attestly.io/internal-error`       | Erro inesperado do servidor.           |
| 503    | `https://errors.attestly.io/database-unavailable` | Problema transiente de infraestrutura. |

Respostas 5xx são repetíveis. Use exponential backoff com jitter; se
persistir, contate `support@attestly.io`.

## Falhas parciais (200)

Falha de source ou check não derruba a request inteira. A resposta é
`200` mas `verdict.status = "degraded"` e o check afetado carrega
`status: "failed"` com mensagem em `error`. Veja
[Verdicts](/pt-BR/concepts/verdicts).