Entender el modelo de créditos y el overage

La API pública de CaptainDNS se factura en créditos. Un lookup DNS simple cuesta 1 credito, un score de deliverability cuesta 30. Cada plan incluye un cupo mensual de créditos; el exceso se factura al final del período para los planes de pago. Esta página explica los detalles.

Principio

Un credito no es una unidad de tiempo ni de datos. Es una unidad de coste interno que refleja la cantidad de trabajo del backend de CaptainDNS:

• 1 credito: un lookup DNS cacheado.
• 2 a 3 créditos: una verificación multi-resolver o una cadena DNSSEC.
• 5 créditos: un blacklist check multi-RBL o un test SMTP completo.
• 10 créditos: un crawl HTTP con extraccion de meta.
• 30 créditos: un score que agrega SPF, DKIM, DMARC, BIMI y reputacion.

Coste por endpoint

La tabla de abajo lista los endpoints principales. Para la lista exhaustiva de los 51 endpoints y sus costes, consulta la referencia OpenAPI. Incluye en particular las 15 herramientas de texto (1 credito cada una) y los endpoints de certificados/BIMI que no se recogen aqui.

Cupos por plan

Facturacion anual con 20 % de descuento (dos meses gratis).

Hard cap: el plan Free no factura overage. Una vez consumidos los 30 créditos, cada peticion devuelve 403 QUOTA_EXCEEDED hasta el final del mes. Para evitar el corte, pasa al plan Starter.

Overage suave: los planes de pago permiten superar el cupo. Los créditos en exceso se contabilizan por separado y se facturan al cierre del mes.

Cabeceras devueltas por la API

Cada respuesta exitosa incluye tres cabeceras contables:

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

• X-Credits-Limit: cupo mensual incluido en el plan actual.
• X-Credits-Remaining: créditos todavia disponibles en la envoltura del plan. Esta cabecera esta topada en 0 y nunca baja a negativo. En overage (solo planes de pago), el valor permanece en 0; para medir el volumen de overage, lee X-Credits-Overage o compara el X-Credits-Consumed acumulado con X-Credits-Limit.
• X-Credits-Consumed: créditos descontados por la peticion actual.

Usa estas cabeceras para dirigir tu cliente: alertar al 80 % del cupo, encolar llamadas no criticas cerca del agotamiento.

Consultar tu uso

El dashboard /account/api-usage muestra el mes en curso y los 12 meses anteriores. La API admin expone los mismos datos en :

{
  "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 sorpresas

Estimacion previa: multiplica el número esperado de peticiones por el coste medio. Un crawler que llame page-crawl-check 10 000 veces al mes consume 100 000 créditos, mas que el cupo Starter.

Backoff cerca del cupo: vigila X-Credits-Remaining y, a partir del 10 % restante, ralentiza o encola las llamadas no urgentes.

Deduplicacion: si tu integración puede recibir peticiones redundantes, usa la idempotencia. Un reintento en las 24 horas devuelve la respuesta almacenada sin consumir créditos adicionales.

Entornos separados: no pongas tu clave cdns_live_* en un job de CI que corre 20 veces por push. Crea una clave cdns_test_* dedicada.

Facturacion del overage

El worker de overage corre a diario a las 03:00 UTC:

1. El sistema identifica periodos cuyo overage no ha sido reportado.
2. Para cada fila con overage_credits > 0, calcula el importe en EUR al tarifa del plan.
3. Llama a POST /subscriptions/{id}/charge en Paddle con una idempotency key estable (sha256(profile_id|YYYY-MM)), lo que elimina las dobles facturaciones.
4. Marca la fila como reportada con el identificador de Paddle.

Ante un 5xx de Paddle, el worker reintenta con backoff exponencial (1s, 5s, 25s). Un 429 de Paddle dispara un backoff fijo de 30s. Los 4xx distintos de 429 no se reintentan automaticamente.

Proximos pasos: el rate limiting explica como suavizar tus llamadas y la idempotencia como ahorrar créditos en los reintentos.