Entender o modelo de créditos e o excedente

A API pública CaptainDNS é cobrada em créditos. Um lookup DNS simples custa 1 crédito, um deliverability score custa 30. Cada plano inclui uma cota mensal de créditos; o excedente é cobrado no fim do período para os planos pagos. Esta página explica os detalhes.

Princípio

Um crédito não é uma unidade de tempo, dados ou requisições. É uma unidade de custo interno que reflete a quantidade de trabalho feita pelo backend CaptainDNS:

• 1 crédito: um lookup DNS em cache.
• 2 a 3 créditos: uma verificação multi-resolver ou uma cadeia DNSSEC.
• 5 créditos: uma verificação blacklist multi-RBL ou um teste SMTP completo.
• 10 créditos: um crawl HTTP com extração de meta.
• 30 créditos: um score que agrega SPF, DKIM, DMARC, BIMI e reputação.

Custo por endpoint

A tabela abaixo lista os principais endpoints. Para a lista exaustiva dos 59 endpoints e seus custos, consulte a referência OpenAPI. Ela inclui especialmente as 15 ferramentas de texto (1 crédito cada) e os endpoints de certificados/BIMI não repetidos aqui.

Cotas por plano

Cobrança anual com 20 % de desconto (dois meses grátis).

Hard cap: o plano Free não cobra excedente. Assim que os 30 créditos são consumidos, cada requisição retorna 403 QUOTA_EXCEEDED até o fim do mês. Para evitar o corte, passe ao plano Starter.

Excedente flexível: os planos pagos permitem ultrapassar a cota. Os créditos em excedente são contabilizados separadamente e cobrados no fim do mês.

Headers retornados pela API

Cada resposta bem-sucedida inclui três headers contábeis:

X-Credits-Limit: 50000
X-Credits-Remaining: 37547
X-Credits-Consumed: 2

• X-Credits-Limit: cota mensal incluída no plano atual.
• X-Credits-Remaining: créditos ainda disponíveis no envelope do plano. Este header é limitado a 0 e nunca fica negativo. Em excedente (somente planos pagos), o valor permanece em 0; para medir o volume de excedente, leia X-Credits-Overage ou compare X-Credits-Consumed acumulado com X-Credits-Limit.
• X-Credits-Consumed: créditos debitados pela requisição em curso.

Use estes headers para dirigir seu cliente: alerta ao atingir 80 % da cota, filas para chamadas não críticas próximas ao esgotamento.

Consultar seu uso

O dashboard /account/api-usage mostra o mês corrente e os 12 anteriores. A API admin expõe os mesmos dados em:

{
  "tier": "starter",
  "credits_limit": 50000,
  "credits_used_current": 12453,
  "credits_remaining": 37547,
  "overage_credits_current": 0,
  "overage_eur_cents_per_1k": 100,
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-05-01T00:00:00Z",
  "history": [
    {
      "period_start": "2026-03-01T00:00:00Z",
      "credits_used": 47821,
      "overage_credits": 0,
      "overage_charged_eur_cents": 0
    }
  ]
}

Evitar surpresas

Estimativa prévia: multiplique o número esperado de requisições pelo custo médio. Um crawler que chama page-crawl-check em 10.000 URLs por mês consome 100.000 créditos, mais do que a cota Starter.

Backoff próximo à cota: monitore X-Credits-Remaining e, aos 10 % restantes, desacelere ou enfileire chamadas não urgentes.

Deduplicação: se sua integração pode receber requisições redundantes, use a idempotência.

Ambientes separados: não coloque sua chave cdns_live_* em um job de CI que roda 20 vezes por push. Crie uma chave cdns_test_* dedicada.

Cobrança do excedente

O excedente é cobrado automaticamente após o fechamento de cada período mensal. O valor é calculado na tarifa do plano e cobrado em uma única transação. Em caso de erros, o sistema tenta novamente automaticamente. Se o problema persistir, entre em contato com o suporte CaptainDNS.

Próximos passos: o rate limiting explica como suavizar suas chamadas e a idempotência como economizar créditos em retries.