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 10 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 reached for the current plan",
  "details": {
    "tier": "starter",
    "limit": 50000,
    "current": 50000
  },
  "request_id": "req_a1b2c3d4"
}

• code: cadena estable documentada aqui. Usala para ramificar tu logica.
• message: descripcion legible en ingles. No la parsees; puede evolucionar.
• details: objeto opcional con contexto específico.
• request_id: identificador de CaptainDNS, útil para abrir un ticket de soporte.

Códigos de autenticación (401)

INVALID_API_KEY

Status: 401. Cabecera Authorization ausente, prefijo ausente o secreto alterado. Accion: verifica la cabecera.

EXPIRED_API_KEY

Status: 401. La clave supero su expires_at. Accion: crea una nueva clave.

REVOKED_API_KEY

Status: 401. La clave fue revocada manualmente o automaticamente. Accion: usa la clave activa.

Códigos de autorizacion (403)

INSUFFICIENT_SCOPE

Status: 403. La clave no lleva el scope requerido.

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Endpoint requires scope 'web:read'",
  "details": {
    "required": "web:read",
    "granted": ["dns:read", "mail:read"]
  }
}

Accion: crea una clave con el scope adecuado.

IP_NOT_ALLOWED

Status: 403. La clave tiene una allowlist y la IP origen no esta en ella.

{
  "code": "IP_NOT_ALLOWED",
  "message": "Source IP not in the allowlist for this API key",
  "details": {
    "detected_ip": "203.0.113.42",
    "allowlist": ["4.175.114.0/23"]
  }
}

Accion: anade tu IP a la allowlist.

QUOTA_EXCEEDED

Status: 403. El cupo mensual de créditos esta agotado y el plan no permite overage.

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached",
  "details": {
    "tier": "free",
    "limit": 500,
    "current": 500,
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z"
  }
}

Accion: espera al siguiente período o cambia de plan.

Códigos de conflicto (409)

IDEMPOTENCY_CONFLICT

Status: 409. Una Idempotency-Key se reutiliza con un body distinto.

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency key reused with a different request body",
  "details": {
    "key": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Accion: genera una nueva clave.

Códigos de rate limit (429)

RATE_LIMITED

Status: 429. El token bucket por clave esta vacio o el límite por IP se supero.

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "details": {
    "scope": "per-key",
    "retry_after_seconds": 12
  }
}

La cabecera Retry-After acompana siempre a este código.

Códigos de servidor (5xx)

INTERNAL_ERROR

Status: 500. Error inesperado en CaptainDNS. Accion: guarda el request_id y abre un ticket.

SERVICE_UNAVAILABLE

Status: 503. Un subsistema requerido por el endpoint no esta disponible.

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Public API is temporarily unavailable",
  "details": {
    "reason": "temporarily_unavailable"
  }
}

Accion: respeta la cabecera Retry-After.

Códigos de validacion (400)

La API devuelve también 400 BAD_REQUEST para errores de validacion especificos de cada endpoint. Estos errores no siguen la envoltura estándar.

Ejemplo con un DNS resolve con dominio inválido:

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

Para los esquemas exactos, consulta la referencia OpenAPI.

Tabla sintetica

Buenas practicas de manejo

• Ramifica sobre el par (status, code): el status por si solo no basta.
• Registra el request_id: imprescindible para el soporte.
• No reintentes a ciegas: los 4xx salvo 429 indican un problema del cliente.
• Respeta Retry-After: los 429 y 503 siempre lo incluyen.
• Alerta sobre tasas de error: 1 % de 5xx en 5 minutos es un incidente.

Sigue con la referencia OpenAPI o vuelve al quickstart.