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 a partir do Pack. 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 a 6 créditos: uma verificação blacklist multi-RBL ou um teste SMTP completo.
• 8 a 10 créditos: um crawl HTTP com extração de meta ou uma detecção de phishing.
• 30 créditos: um score que agrega SPF, DKIM, DMARC, BIMI e reputação.

Assim você estima o consumo de uma integração sem contar requisição por requisição: multiplique pelo custo médio dos endpoints chamados e você tem o volume mensal aproximado.

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

Hard cap: o plano Free não cobra excedente. Assim que os créditos incluídos são consumidos (30 no Free), cada requisição retorna 403 QUOTA_EXCEEDED até o fim do mês.

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

Uma assinatura histórica mantém a cota de créditos do seu plano.

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 (do Pack para cima), 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 CaptainDNS (Perfil > Chaves API) mostra o mês corrente e os 12 anteriores, com o detalhe dos créditos consumidos, do excedente e do histórico de faturamento.

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

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.