API-Fehler verstehen und behandeln

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

Standardhülle

Jede Fehlerantwort folgt diesem Format:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached for the current plan",
  "details": {
    "tier": "starter",
    "limit": 50000,
    "current": 50000
  },
  "request_id": "req_a1b2c3d4"
}

• code: stabiler String (siehe Liste unten).
• message: englische lesbare Beschreibung. Nicht parsen.
• details: optionales Objekt mit code-spezifischem Kontext.
• request_id: Identifier für Support-Tickets.

Authentifizierungscodes (401)

INVALID_API_KEY

Status: 401. Header Authorization fehlt, Präfix falsch oder Geheimnis manipuliert. Aktion: Header prüfen, keine Leerzeichen oder Zeilenumbrüche einschleusen.

EXPIRED_API_KEY

Status: 401. Der Schlüssel hat sein expires_at überschritten. Aktion: neuen Schlüssel erstellen.

REVOKED_API_KEY

Status: 401. Schlüssel wurde manuell oder automatisch widerrufen. Aktion: aktiven Schlüssel verwenden oder neuen erstellen.

Autorisierungscodes (403)

INSUFFICIENT_SCOPE

Status: 403. Der Schlüssel trägt den geforderten Scope nicht.

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

Aktion: einen Schlüssel mit dem fehlenden Scope erstellen.

IP_NOT_ALLOWED

Status: 403. Der Schlüssel hat eine IP-Allowlist und die Quell-IP passt nicht.

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

Aktion: IP der Allowlist hinzufügen oder über einen autorisierten Egress routen.

QUOTA_EXCEEDED

Status: 403. Das monatliche Credit-Kontingent ist erreicht und der Plan erlaubt keine 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"
  }
}

Aktion: bis zur nächsten Periode warten oder Plan aufrüsten.

Konfliktcodes (409)

IDEMPOTENCY_CONFLICT

Status: 409. Ein Idempotency-Key wurde mit einem abweichenden Body wiederverwendet.

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

Aktion: neuen Schlüssel generieren.

Rate-Limit-Codes (429)

RATE_LIMITED

Status: 429. Der Token Bucket pro Schlüssel ist leer oder das Limit pro IP ist überschritten.

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

Der Retry-After-Header begleitet diesen Code immer.

Servercodes (5xx)

INTERNAL_ERROR

Status: 500. Unerwarteter Fehler auf Seite CaptainDNS. Aktion: request_id notieren und Support-Ticket öffnen, in einigen Minuten erneut versuchen.

SERVICE_UNAVAILABLE

Status: 503. Ein vom Endpunkt benötigtes Subsystem ist nicht verfügbar.

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

Aktion: Retry-After beachten, bei anhaltendem Problem Support kontaktieren.

Validierungscodes (400)

400 BAD_REQUEST-Antworten folgen nicht der 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"
}

Schemadetails in der OpenAPI-Referenz.

Übersichtstabelle

Best Practices beim Fehlerhandling

• Auf das Paar (status, code) verzweigen: der Status allein reicht nicht.
• request_id protokollieren: unverzichtbar für den Support.
• Nicht blind wiederholen: 4xx außer 429 brauchen eine Code-Änderung.
• Retry-After respektieren: 429 und 503 enthalten ihn immer.
• Auf Fehlerraten alarmieren: 1 % 5xx über ein 5-Minuten-Fenster ist ein Incident-Signal.

Weiter mit der OpenAPI-Referenz oder zurück zum Schnellstart.