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

# Cobrança

> Como as requisições cobráveis são contabilizadas, idempotência e política de DEGRADED.

Esta página descreve como a API mede e cobra requisições. Aplica-se
quando sua Organização tem assinatura ativa e usa uma chave `atk_*`.

## O que conta como requisição cobrável

| Conta                    | Não conta                      |
| ------------------------ | ------------------------------ |
| `POST /v1/evaluate`      | `GET /v1/sources`              |
| `POST /v1/intersections` | `GET /v1/rulesets` (list/get)  |
| `POST /v1/distance`      | `POST /v1/rulesets` (create)   |
| `POST /v1/subjects`      | `?explain=true` (só metadados) |

Leituras de catálogo, gravações de ruleset e chamadas `?explain=true`
nunca consomem cota e nunca são cobradas.

## Portões por requisição

Toda requisição cobrável passa por três portões, em ordem:

1. **Autenticação** — o bearer token precisa ser uma chave `atk_*`
   válida emitida para sua Organização.
2. **Assinatura** — sua assinatura precisa estar ativa. Assinatura
   expirada ou suspensa retorna `402 SUBSCRIPTION_INACTIVE` e a
   requisição não é executada.
3. **Cota** — você precisa estar dentro do teto mensal contratado para
   o período corrente. Acima do teto retorna `429 QUOTA_EXCEEDED` e a
   requisição não é executada.

Uma requisição que falha em qualquer um desses portões **não é
cobrada**.

## Período de cobrança

A cota é contada contra o seu **período de cobrança no Stripe**, não
contra o mês calendário. Os limites vêm da sua assinatura —
tipicamente o dia do mês em que você assinou — e são retornados nos
campos `period_started_at` / `period_ends_at` em respostas `429`. Veja
[Cotas e rate limits](/pt-BR/reference/quotas).

## Idempotência

Envie o header `Idempotency-Key` em toda requisição cobrável:

```http theme={null}
POST /v1/evaluate
Idempotency-Key: client-job-2026-04-18-7842
Content-Type: application/json
Authorization: Bearer atk_live_...
```

Formato: `[A-Za-z0-9_:.-]{8,128}`. Qualquer outro valor retorna
`422 IDEMPOTENCY_KEY_INVALID`.

Chaves são escopadas por Organização. O contrato:

| Resultado                        | HTTP | Significado                                                           |
| -------------------------------- | ---- | --------------------------------------------------------------------- |
| Mesma chave, mesmo body, cobrada | 200  | Replay — o snapshot original é retornado.                             |
| Mesma chave, body diferente      | 422  | `IDEMPOTENCY_KEY_CONFLICT` — escolha nova chave.                      |
| Mesma chave, retries demais      | 429  | `IDEMPOTENCY_KEY_EXHAUSTED` — escolha nova chave.                     |
| Mesma chave, snapshot expirado   | 410  | `IDEMPOTENCY_REPLAY_EXPIRED` — chave reutilizável para nova cobrança. |

<Note>
  O replay retorna a resposta original **sem re-executar a avaliação e
  sem cobrar de novo**. É a forma segura de fazer retry em erros de
  rede: a segunda requisição ou repete o resultado anterior (sem
  cobrança extra) ou executa do zero (uma cobrança no total).
</Note>

## Respostas DEGRADED não são cobradas

Uma resposta com `status: "degraded"` significa que pelo menos uma
fonte não pôde ser avaliada por motivo de infraestrutura (timeout do
provedor upstream, erro transitório). A resposta é **incompleta**,
não errada.

Por padrão, **respostas DEGRADED não consomem cota e não são
cobradas**. A `Idempotency-Key` permanece reutilizável, então você
pode tentar a mesma requisição de novo quando a fonte upstream se
recuperar — o retry vai ou ter sucesso (uma cobrança no total) ou
voltar DEGRADED de novo (continua zero cobranças).

Para os wrappers `/v1/intersections`, `/v1/distance` e `/v1/subjects`,
uma fonte que falha individualmente é reportada com `status: "failed"`
no seu `SourceOutcome`. A resposta global ainda pode ser útil — as
outras fontes retornaram dados — mas a requisição não é cobrada.

Veja [Verdicts](/pt-BR/concepts/verdicts) para a semântica completa de
status/outcome.

## Estratégia de retry recomendada

1. Gere uma `Idempotency-Key` nova por job lógico (um UUID, ou seu
   próprio job id).
2. Em `5xx`, erro de rede ou `status: "degraded"`: refaça com a
   **mesma** chave. Vai ou repetir um resultado já cobrado, ou
   executar do zero.
3. Em `429 QUOTA_EXCEEDED`: pare até `period_ends_at` ou nos contate
   para aumentar o teto.
4. Em `429 RATE_LIMIT_EXCEEDED`: aguarde `Retry-After` segundos com
   backoff exponencial e jitter.
5. Em `422 IDEMPOTENCY_KEY_CONFLICT` ou `429 IDEMPOTENCY_KEY_EXHAUSTED`:
   escolha uma chave nova (a original está travada em outro payload).

## Erros

Todos os erros relacionados a billing seguem o envelope padrão.
Compare contra o campo `code`, não contra `title` ou `detail`. Veja
[Erros](/pt-BR/reference/errors) para a lista completa de códigos.