API-Fehler verstehen und behandeln

Die CaptainDNS Public API liefert alle Fehler in einer standardisierten JSON-Hülle. Diese Seite listet die kanonischen Codes, ihre Bedeutung und die empfohlene Korrekturmaßnahme.

Standardhülle

Jede Fehlerantwort folgt diesem Format:

{
  "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: stabiler String, hier dokumentiert. Nutze ihn, um deine Fehlerbehandlungslogik anzubinden.
message: englische lesbare Beschreibung. Nicht parsen; sie kann sich ändern.
details: optionales Objekt mit code-spezifischem Kontext. Das Schema variiert je nach Code. Die meisten Codes stellen keine details bereit: die Information liegt dann in message.
request_id: CaptainDNS-Identifier der Anfrage, nützlich zum Öffnen eines Support-Tickets. Nur vorhanden, wenn der Header X-Request-Id propagiert wurde.
documentation_url: Link zu dieser Seite.

Der HTTP-Status begleitet stets den Code. Ein robuster Client verzweigt auf das Paar (status, code) und priorisiert code.

Ursache: fehlender Authorization-Header, fehlendes Präfix, schlecht geformter Schlüssel, manipuliertes Geheimnis oder unbekannter Schlüssel bei CaptainDNS. Ein HMAC-Mismatch und ein "unbekannter Schlüssel" liefern denselben Code, um beides aus Angreifersicht nicht zu unterscheiden.

Aktion: prüfe, dass der Header tatsächlich Authorization: Bearer cdns_live_... lautet. Ein versehentliches Leerzeichen, ein Zeilenumbruch oder ein gekürzter Schlüssel sind die häufigsten Ursachen.

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

Kein details-Feld; die Information steht nur in message.

EXPIRED_API_KEY

Status: 401.

Ursache: der Schlüssel hat sein expires_at überschritten.

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

Kein details-Feld.

Aktion: erstelle einen neuen Schlüssel mit einem späteren Ablaufdatum oder ohne Ablauf. Schlüssel ohne expires_at bleiben gültig, solange sie nicht widerrufen werden.

REVOKED_API_KEY

Status: 401.

Ursache: der Schlüssel wurde manuell oder automatisch widerrufen (Ende der Rotations-Grace-Period).

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

Kein details-Feld.

Aktion: verwende den aktiven Schlüssel. Falls keiner vorhanden ist, erstelle einen neuen über das Dashboard.

Autorisierungscodes (403)

INSUFFICIENT_SCOPE

Status: 403.

Ursache: der Schlüssel trägt den vom Endpunkt geforderten Scope nicht. Der fehlende Scope wird an message angehängt.

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

Kein details-Feld; der erforderliche Scope wird aus message gelesen.

Aktion: erstelle einen neuen Schlüssel mit dem fehlenden Scope oder verwende einen Schlüssel, der ihn bereits trägt. Scopes sind nach der Erstellung nicht mehr änderbar.

IP_NOT_ALLOWED

Status: 403.

Ursache: der Schlüssel hat eine IP-Allowlist und die IP der Anfrage gehört nicht dazu. Die Client-IP wird serverseitig aus r.RemoteAddr abgeleitet (niemals aus einem clientseitig gesetzten X-Forwarded-For), nach eventueller Umschreibung durch die TrustedProxyRealIP-Schicht, wenn der unmittelbare Hop ein bei CaptainDNS konfigurierter vertrauenswürdiger Proxy ist.

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

Kein details-Feld; die erkannte IP und die CIDR-Liste werden nicht an den Client zurückgegeben (sie werden serverseitig protokolliert).

Aktion: füge deine IP der Allowlist des Schlüssels hinzu oder route deinen Traffic über einen autorisierten Egress (Proxy, NAT).

QUOTA_EXCEEDED

Status: 403.

Ursache: das monatliche Credit-Kontingent ist erreicht und der Plan erlaubt keine Overage (Free-Plan, 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"
}

Aktion: warte auf die nächste Periode oder wechsle zu einem höheren Plan. Das CaptainDNS-Dashboard erlaubt den Planwechsel mit einem Klick.

OVERAGE_BUDGET_EXCEEDED

Status: 403.

Ursache: das Profil hat die Overage aktiviert, aber das im Dashboard konfigurierte monatliche Budgetlimit erreicht. Nachfolgende Aufrufe werden abgelehnt, bis die Periode endet oder das Limit angehoben wird.

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

Aktion: hebe das Limit unter Account > API usage an, wechsle zu einem Plan mit größerem Kontingent oder warte auf die nächste Monatsperiode.

Request-Codes (400)

INVALID_REQUEST

Status: 400.

Ursache: ein Bestandteil der Anfrage ist nicht verwertbar. Zwei Fälle werden von der Public API ausgegeben:

Schlecht geformter Idempotency-Key-Header (Nicht-ASCII-Zeichen, Leerzeichen, Länge außerhalb der Grenzen, nach Trim leerer Wert).
Unlesbarer Request-Body oder Überschreitung des Idempotenz-Limits (11 MiB).

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

Kein details-Feld; der genaue Grund steht in message.

Aktion: korrigiere den Header oder den Body und versuche es erneut. Endpunkt-spezifische Validierungsfehler (ungültige Domain, unbekannter Selector usw.) sind im Abschnitt Validierungscodes (400) beschrieben.

Konfliktcodes (409)

IDEMPOTENCY_CONFLICT

Status: 409.

Ursache: ein Idempotency-Key wird mit einem Body wiederverwendet, der von der ursprünglichen Anfrage abweicht. Der Vergleich erfolgt über den SHA-256-Hash des rohen Bodys.

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

Kein details-Feld; der konfliktbehaftete Key ist derjenige, den du gerade gesendet hast.

Aktion: generiere einen neuen Key für die neue Anfrage oder korrigiere den Client, der den Body zwischen Retries verändert.

Rate-Limit-Codes (429)

RATE_LIMITED

Status: 429.

Ursache: der Token Bucket pro Schlüssel ist leer oder das Rate Limit pro IP ist überschritten. Zwei message-Varianten je nach erreichter Stufe:

Pre-Auth-IP-Bucket: "Too many requests from this IP. Slow down.".
Per-Key-Bucket: "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"
}

Kein details-Feld. Der Retry-After-Header begleitet diesen Code immer, in Sekunden. Warte mindestens diese Dauer, bevor du erneut versuchst. Siehe Rate Limiting-Handbuch für Backoff-Strategien.

Servercodes (5xx)

INTERNAL_ERROR

Status: 500 oder 503.

Ursache: unerwarteter Fehler bei CaptainDNS. Zwei Varianten:

500: transienter Applikationsfehler (Handler-Panic, nicht verfügbare DB-Abhängigkeit, Tier-Lookup-Fehler usw.). message benennt das Subsystem.
503: die Public API ist nicht konfiguriert oder die Gruppe /public/v1/* wurde plattformseitig explizit deaktiviert (fehlender Pepper, Flag PUBLICAPI_ENABLED=false). Es gibt keinen eigenen SERVICE_UNAVAILABLE-Code: die Nichtverfügbarkeit teilt sich den Code INTERNAL_ERROR mit Status 503.

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

Kein details-Feld.

Aktion: notiere die request_id und öffne ein Support-Ticket. 503 hängen in der Regel mit einer geplanten Wartung oder einem Incident zusammen: prüfe den offiziellen Statuskanal, bevor du es erneut versuchst. Versuche es nach einigen Minuten erneut bei transienten 500; wenn die Rate 1 % über ein 5-Minuten-Fenster übersteigt, alarmiere das CaptainDNS-Team.

Validierungscodes (400)

Die API liefert zusätzlich 400 BAD_REQUEST für endpunkt-spezifische Validierungsfehler. Diese Fehler folgen nicht der obigen Standardhülle, da ihr Schema je Endpunkt variiert.

Beispiel für einen DNS-Resolve mit ungültiger Domain:

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

Für Endpunkte, die Validierungsfehler zurückgeben, siehe die OpenAPI-Referenz mit den exakten Schemas.

Übersichtstabelle

Status	Code	Beschreibung	Aktion
400	Variabel	Endpunkt-Validierungsfehler	Request-Body korrigieren
400	`INVALID_REQUEST`	`Idempotency-Key` oder unlesbarer Body	Header oder Body korrigieren
401	`INVALID_API_KEY`	Schlüssel fehlt, ist schlecht geformt oder unbekannt	`Authorization`-Header prüfen
401	`EXPIRED_API_KEY`	Abgelaufener Schlüssel	Neuen Schlüssel erstellen
401	`REVOKED_API_KEY`	Widerrufener Schlüssel	Aktiven Schlüssel verwenden
403	`INSUFFICIENT_SCOPE`	Fehlender Scope am Schlüssel	Schlüssel mit passendem Scope erstellen
403	`IP_NOT_ALLOWED`	IP nicht auf der Allowlist	IP hinzufügen oder autorisierten Egress nutzen
403	`QUOTA_EXCEEDED`	Monatskontingent erreicht (Hard Cap)	Warten oder Upgrade
403	`OVERAGE_BUDGET_EXCEEDED`	Overage-Budget erreicht	Limit anheben oder Upgrade
409	`IDEMPOTENCY_CONFLICT`	Gleicher Key mit anderem Body	Neuen Key generieren
429	`RATE_LIMITED`	Rate Limit IP oder pro Schlüssel überschritten	`Retry-After` abwarten
500	`INTERNAL_ERROR`	Transienter Serverfehler	Retry plus Support-Ticket bei Persistenz
503	`INTERNAL_ERROR`	Public API nicht konfiguriert	Status prüfen, erneut versuchen

Best Practices beim Fehlerhandling

Auf das Paar (status, code) verzweigen. Der Status allein reicht nicht: zwei 403 können von INSUFFICIENT_SCOPE oder IP_NOT_ALLOWED kommen, die unterschiedliche Aktionen erfordern.
request_id protokollieren. Sie ist der eindeutige Request-Identifier bei CaptainDNS und für jede Support-Untersuchung erforderlich.
Nicht blind wiederholen. 4xx außer 429 deuten auf ein clientseitiges Problem hin: ein Retry ohne Änderung bringt nichts.
Retry-After respektieren. 429 und 503 enthalten ihn systematisch. Kurzschließen ist eine schlechte Idee.
Auf Fehlerraten alarmieren. 1 % 5xx über ein 5-Minuten-Fenster ist ein Incident-Signal. Melde es an dein Observability-System.

Weiter mit der OpenAPI-Referenz, um Schemas Endpunkt für Endpunkt zu erkunden, oder zurück zum Quickstart, wenn du von vorn beginnen möchtest.