Capire è gestire gli errori della API

La API pubblica CaptainDNS restituisce tutti gli errori in un involucro JSON standardizzato. Questa pagina elenca i 10 codici canonici, il loro significato è l'azione correttiva raccomandata.

Involucro standard

Ogni risposta d'errore segue questo 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: stringa stabile. Usala per diramare la logica di gestione.
• message: descrizione leggibile in inglese. Non parse.
• details: oggetto opzionale con contesto specifico.
• request_id: identificatore CaptainDNS, utile per il supporto.

Codici di autenticazione (401)

INVALID_API_KEY

Status: 401. Header Authorization mancante, prefisso assente o segreto alterato. Azione: verifica l'header.

EXPIRED_API_KEY

Status: 401. La chiave ha superato expires_at. Azione: crea una nuova chiave.

REVOKED_API_KEY

Status: 401. La chiave è stata revocata. Azione: usa una chiave attiva.

Codici di autorizzazione (403)

INSUFFICIENT_SCOPE

Status: 403. La chiave non ha lo scope richiesto.

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

Azione: crea una chiave con lo scope mancante.

IP_NOT_ALLOWED

Status: 403. La chiave ha un'allowlist IP è la IP sorgente non vi compare.

{
  "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"]
  }
}

Azione: aggiungi l'IP all'allowlist.

QUOTA_EXCEEDED

Status: 403. La quota mensile di crediti è raggiunta è il piano non ammette 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"
  }
}

Azione: attendi il periodo successivo o cambia piano.

Codici di conflitto (409)

IDEMPOTENCY_CONFLICT

Status: 409. Una Idempotency-Key viene riutilizzata con body diverso.

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

Azione: genera una nuova chiave.

Codici di rate limit (429)

RATE_LIMITED

Status: 429. Il token bucket per chiave è vuoto o il rate limit per IP è stato superato.

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

L'header Retry-After accompagna sempre questo codice.

Codici server (5xx)

INTERNAL_ERROR

Status: 500. Errore inaspettato lato CaptainDNS. Azione: mantieni il request_id è apri un ticket.

SERVICE_UNAVAILABLE

Status: 503. Un sottosistema richiesto non è disponibile.

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

Azione: rispetta Retry-After, se persiste contatta il supporto.

Codici di validazione (400)

L'API restituisce anche 400 BAD_REQUEST per errori di validazione specifici di ogni endpoint. Questi errori non seguono l'involucro standard.

Esempio:

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

Per gli schemi esatti consulta la referenza OpenAPI.

Tabella sintetica

Buone pratiche di gestione

• Dirama sulla coppia (status, code): lo status da solo non basta.
• Registra il request_id: indispensabile per il supporto.
• Non riprovare ciecamente: i 4xx salvo 429 richiedono una correzione.
• Rispetta Retry-After: i 429 e 503 lo includono sempre.
• Allerta sui tassi d'errore: 1 % di 5xx su 5 minuti è un segnale di incident.

Passa alla referenza OpenAPI o torna al quickstart.