Entender y tratar los errores de la API

La API pública de CaptainDNS devuelve todos los errores en una envoltura JSON estandarizada. Esta página lista los códigos canonicos, su significado y la accion correctiva recomendada.

Envoltura estándar

Toda respuesta de error sigue este formato:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota exceeded for plan 'starter'.",
  "details": {
    "tier": "starter",
    "credits_used": 50000,
    "credits_limit": 50000
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

code: cadena estable documentada aqui. Usala para ramificar tu logica de manejo de errores.
message: descripcion legible en ingles. No la parsees; puede evolucionar.
details: objeto opcional con contexto específico al código. Su esquema varia segun el código. La mayoria de los códigos no exponen details: la información va entonces en message.
request_id: identificador CaptainDNS de la peticion, útil para abrir un ticket de soporte. Presente solo si la cabecera X-Request-Id se propago.
documentation_url: enlace a esta página.

El status HTTP acompana siempre al código. Un cliente robusto ramifica sobre el par (status, code) y trata code como prioritario.

Códigos de autenticación (401)

Causa: cabecera Authorization ausente, prefijo ausente, clave malformada, secreto alterado o clave desconocida del lado CaptainDNS. Un HMAC mismatch y una "clave desconocida" devuelven el mismo código para no distinguir ambos casos del lado atacante.

Accion: verifica que la cabecera sea Authorization: Bearer cdns_live_.... Un espacio parasito, un salto de linea o una clave truncada son las causas mas frecuentes.

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details; la información va unicamente en message.

EXPIRED_API_KEY

Status: 401.

Causa: la clave supero su expires_at.

{
  "code": "EXPIRED_API_KEY",
  "message": "This API key has expired.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details.

Accion: crea una nueva clave con una fecha de expiracion mas lejana o sin expiracion. Las claves sin expires_at son validas mientras no se revoquen.

REVOKED_API_KEY

Status: 401.

Causa: la clave fue revocada manualmente o automaticamente (fin del grace period de rotación).

{
  "code": "REVOKED_API_KEY",
  "message": "This API key has been revoked.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details.

Accion: usa la clave activa. Si no tienes ninguna, crea una desde el dashboard.

Códigos de autorizacion (403)

INSUFFICIENT_SCOPE

Status: 403.

Causa: la clave no tiene el scope requerido por el endpoint. El scope faltante va concatenado en message.

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key does not have the required scope: web:read",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details; el scope requerido se lee desde message.

Accion: crea una nueva clave con el scope faltante o usa una clave que ya lo lleve. Los scopes no son modificables despues de la creacion.

IP_NOT_ALLOWED

Status: 403.

Causa: la clave tiene una allowlist de IP y la IP de la peticion no esta en ella. La IP cliente se deriva de r.RemoteAddr del lado backend (nunca de un X-Forwarded-For enviado por el cliente), tras una posible reescritura por la capa TrustedProxyRealIP si el hop inmediato es un proxy de confianza configurado del lado CaptainDNS.

{
  "code": "IP_NOT_ALLOWED",
  "message": "Your IP is not in this key's allowlist.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details; la IP detectada y la lista CIDR no se devuelven al cliente (se registran del lado servidor).

Accion: anade tu IP a la allowlist de la clave, o enruta tu trafico por un egress autorizado (proxy, NAT).

QUOTA_EXCEEDED

Status: 403.

Causa: el cupo mensual de créditos se alcanzo y el plan no autoriza overage (plan Free, hard cap).

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota exceeded for plan 'free'.",
  "details": {
    "tier": "free",
    "credits_used": 500,
    "credits_limit": 500
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Accion: espera al siguiente período o cambia a un plan superior. El dashboard CaptainDNS permite cambiar de plan en un clic.

OVERAGE_BUDGET_EXCEEDED

Status: 403.

Causa: el perfil activo el overage pero alcanzo el tope presupuestario mensual configurado en el dashboard. Las llamadas siguientes se rechazan hasta el cierre del período o la subida del tope.

{
  "code": "OVERAGE_BUDGET_EXCEEDED",
  "message": "Overage budget cap reached for plan 'starter'.",
  "details": {
    "tier": "starter",
    "credits_used": 68000,
    "credits_limit": 50000
  },
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Accion: sube el tope desde Account > API usage, pasa a un plan con cupo mayor, o espera al siguiente período mensual.

Códigos de peticion (400)

INVALID_REQUEST

Status: 400.

Causa: un componente de la peticion no es utilizable. La API pública emite dos casos:

Cabecera Idempotency-Key malformada (caracteres no ASCII, espacios, longitud fuera de rango, valor vacio tras trim).
Body de peticion ilegible o que supera el limite de idempotencia (11 MiB).

{
  "code": "INVALID_REQUEST",
  "message": "Invalid Idempotency-Key header.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details; el motivo preciso va en message.

Accion: corrige la cabecera o el body y reintenta. Para los errores de validacion especificos a un endpoint (dominio invalido, selector desconocido, etc.), consulta la seccion Códigos de validacion (400).

Códigos de conflicto (409)

IDEMPOTENCY_CONFLICT

Status: 409.

Causa: una clave Idempotency-Key se reutiliza con un body distinto al de la peticion original. La comparacion se hace sobre el hash SHA-256 del body bruto.

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency-Key reused with a different request body.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details; la clave en conflicto es la que acabas de enviar.

Accion: genera una nueva clave para la nueva peticion, o corrige el cliente que modifica el body entre reintentos.

Códigos de rate limit (429)

RATE_LIMITED

Status: 429.

Causa: el token bucket por clave esta vacio o se supero el rate limit por IP. Dos variantes de message segun la capa alcanzada:

Bucket IP pre-auth: "Too many requests from this IP. Slow down.".
Bucket por clave: "Rate limit exceeded for this API key.".

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded for this API key.",
  "request_id": "req_a1b2c3d4",
  "documentation_url": "https://www.captaindns.com/en/docs/api/errors"
}

Sin campo details. La cabecera Retry-After acompana siempre este código, expresada en segundos. Espera al menos esa duracion antes de reintentar. Consulta la guia de rate limiting para las estrategias de backoff.

Códigos de servidor (5xx)

INTERNAL_ERROR

Status: 500 o 503.

Causa: error inesperado del lado CaptainDNS. Dos variantes:

500: error aplicativo transitorio (panic de handler, dependencia DB no disponible, error de lookup de tier, etc.). El message precisa el subsistema.
503: la API pública no esta configurada o el grupo /public/v1/* esta explicitamente desactivado del lado plataforma (pepper ausente, flag PUBLICAPI_ENABLED=false). No existe un código SERVICE_UNAVAILABLE distinto: la indisponibilidad comparte el código INTERNAL_ERROR con un status 503.

{
  "code": "INTERNAL_ERROR",
  "message": "public api is not configured",
  "request_id": "req_a1b2c3d4"
}

Sin campo details.

Accion: anota el request_id y abre un ticket de soporte. Los 503 suelen estar ligados a una mantenimiento planificada o un incidente: consulta el canal de estado oficial antes de reintentar. Reintenta tras unos minutos los 500 transitorios; si la tasa supera el 1 % en una ventana de cinco minutos, alerta al equipo CaptainDNS.

Códigos de validacion (400)

La API también devuelve 400 BAD_REQUEST para los errores de validacion especificos de cada endpoint. Estos errores no estan cubiertos por la envoltura estandarizada anterior porque su estructura varia segun el endpoint.

Ejemplo con un DNS resolve con dominio invalido:

{
  "error": "invalid domain: must be a valid FQDN",
  "field": "domain"
}

Para los endpoints que devuelven errores de validacion, consulta la referencia OpenAPI que documenta los esquemas exactos.

Tabla sintetica

Status	Code	Descripcion	Accion
400	Variable	Error de validacion de endpoint	Corregir el body de la peticion
400	`INVALID_REQUEST`	`Idempotency-Key` o body ilegible	Corregir la cabecera o el body
401	`INVALID_API_KEY`	Clave ausente, malformada o desconocida	Verificar la cabecera `Authorization`
401	`EXPIRED_API_KEY`	Clave expirada	Crear una nueva clave
401	`REVOKED_API_KEY`	Clave revocada	Usar una clave activa
403	`INSUFFICIENT_SCOPE`	Scope faltante en la clave	Crear una clave con el scope correcto
403	`IP_NOT_ALLOWED`	IP fuera de la allowlist	Anadir la IP o pasar por un egress autorizado
403	`QUOTA_EXCEEDED`	Cupo mensual alcanzado (hard cap)	Esperar o subir de plan
403	`OVERAGE_BUDGET_EXCEEDED`	Tope de overage alcanzado	Subir el tope o cambiar de plan
409	`IDEMPOTENCY_CONFLICT`	Misma clave con body distinto	Generar una nueva clave
429	`RATE_LIMITED`	Rate limit por IP o por clave superado	Esperar `Retry-After`
500	`INTERNAL_ERROR`	Error de servidor transitorio	Reintentar y abrir ticket si persiste
503	`INTERNAL_ERROR`	API pública no configurada	Verificar el estado, reintentar

Buenas practicas de manejo

Ramifica sobre el par (status, code). El status por si solo no basta: dos 403 pueden venir de INSUFFICIENT_SCOPE o de IP_NOT_ALLOWED, que merecen acciones distintas.
Registra el request_id. Es el identificador unico de la peticion del lado CaptainDNS y es imprescindible para toda investigacion de soporte.
No reintentes a ciegas. Los 4xx salvo 429 indican un problema del cliente: reintentar sin cambios no funcionara.
Respeta Retry-After. Los 429 y 503 lo incluyen siempre. No lo saltees.
Alerta sobre las tasas de error. 1 % de 5xx en una ventana de 5 minutos es una senal de incidente. Elevalo a tu observabilidad.

Sigue con la referencia OpenAPI para explorar los esquemas endpoint por endpoint, o vuelve al quickstart si quieres retomar desde el principio.