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 plano Starter. 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 deteção de phishing.
• 30 créditos: um score que agrega SPF, DKIM, DMARC, BIMI e reputação.

Assim é possível estimar o consumo de uma integração sem contar as requisições uma a uma: basta multiplicar pelo custo médio dos endpoints chamados para obter o volume mensal aproximado.

Custo por endpoint

A tabela abaixo lista os principais endpoints. Para a lista exaustiva dos 59 endpoints e os 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

Faturação anual: são faturados 12 meses e pagam-se apenas 10, ou seja, dois meses grátis.

Hard cap: os planos Free e Solo não cobram excedente. Assim que os créditos incluídos são consumidos (30 no Free, 5 000 no Solo), cada requisição retorna 403 QUOTA_EXCEEDED até ao fim do mês. Para evitar o corte, passe ao plano Starter.

Excedente flexível: a partir do Starter, os planos 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 contabilísticos:

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 Starter 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 o seu cliente: alerta ao atingir 80 % da cota, filas para chamadas não críticas próximas ao esgotamento.

Consultar o 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 faturação.

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: monitorize X-Credits-Remaining e, aos 10 % restantes, desacelere ou enfileire chamadas não urgentes.

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

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

Cobrança do excedente

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

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