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 25. 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 siguiente tabla es la unica fuente de verdad, alineada con el especificacion OpenAPI.

Cupos por plan

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

Hard cap: el plan Free no factura overage. Una vez consumidos los 500 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

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.