Pular para o conteúdo principal

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.

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

ContaNão conta
POST /v1/evaluateGET /v1/sources
POST /v1/intersectionsGET /v1/rulesets (list/get)
POST /v1/distancePOST /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.

​
Idempotência

Envie o header Idempotency-Key em toda requisição cobrável: 
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:
ResultadoHTTPSignificado
Mesma chave, mesmo body, cobrada200Replay — o snapshot original é retornado.
Mesma chave, body diferente422IDEMPOTENCY_KEY_CONFLICT — escolha nova chave.
Mesma chave, retries demais429IDEMPOTENCY_KEY_EXHAUSTED — escolha nova chave.
Mesma chave, snapshot expirado410IDEMPOTENCY_REPLAY_EXPIRED — chave reutilizável para nova cobrança.
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).

​
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 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 para a lista completa de códigos.