API: Fehlercodes

Fehlerantwort-Format

Alle API-Fehler geben ein JSON-Objekt mit einem error-Schlüssel zurück, der einen maschinenlesbaren code und eine menschenlesbare message enthält.

{
  "error": {
    "code": "error_code_string",
    "message": "Description of what went wrong"
  }
}

Einige Validierungsfehler enthalten ein details-Feld mit feldspezifischen Informationen:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": {
      "name": "is required"
    }
  }
}

HTTP-Statuscodes

Fehlercode-Referenz

unauthorized

HTTP-Status: 401

Wird zurückgegeben, wenn der API-Schlüssel fehlt, ungültig oder abgelaufen ist.

Mögliche Ursachen: - Kein Authorization-Header in der Anfrage - Das Bearer-Token stimmt mit keinem aktiven API-Schlüssel überein - Der API-Schlüssel wurde im Dashboard widerrufen - Der API-Schlüssel hat sein Ablaufdatum überschritten

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

So behebst du das: - Stelle sicher, dass dein API-Schlüssel im Authorization-Header als Bearer oc_live_... enthalten ist - Prüfe, ob der Schlüssel nicht unter Dashboard > Einstellungen > API-Schlüssel widerrufen wurde - Erstelle einen neuen Schlüssel, wenn der aktuelle abgelaufen ist

forbidden

HTTP-Status: 403

Wird zurückgegeben, wenn dein API-Schlüssel gültig ist, aber die Berechtigungen für die angefragte Aktion fehlen.

{
  "error": {
    "code": "forbidden",
    "message": "Access denied"
  }
}

So behebst du das: - Überprüfe, ob dein Account Zugriff auf die angeforderte Ressource hat - Kontaktiere den Support, falls du glaubst, dass es sich um einen Fehler handelt

not_found

HTTP-Status: 404

Die angeforderte Ressource existiert nicht oder gehört zu einem anderen Account. Aus Sicherheitsgründen unterscheidet die API nicht zwischen "existiert nicht" und "gehört jemand anderem".

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

So behebst du das: - Überprüfe die Ressourcen-ID in deiner Anfrage-URL - Verwende die Listen-Endpunkte, um gültige Ressourcen-IDs zu finden - Stelle sicher, dass die Ressource nicht gelöscht wurde

unprocessable_entity

HTTP-Status: 422

Die Anfrage wurde verstanden, kann aber nicht verarbeitet werden. Dies umfasst Validierungsfehler und Geschäftslogik-Einschränkungen.

Häufige Szenarien:

Starten einer Instanz, die bereits läuft: json { "error": { "code": "unprocessable_entity", "message": "Instance is already running" } }

Löschen einer Abo-basierten Instanz über die API: json { "error": { "code": "unprocessable_entity", "message": "This instance cannot be deleted. Only daily billing instances can be deleted via API." } }

Ungültige Paketauswahl beim Kauf: json { "error": { "code": "unprocessable_entity", "message": "Invalid package index. Please select a valid Claw package." } }

Wiederherstellen eines Backups, während die Instanz läuft: json { "error": { "code": "unprocessable_entity", "message": "Instance must be stopped or paused before restoring a backup." } }

So behebst du das: - Lies das message-Feld für spezifische Hinweise - Prüfe den aktuellen Zustand der Ressource, bevor du Aktionen ausführst - Nutze den Instanz-Details abrufen Endpunkt, um die Felder can_start, can_stop und can_restart zu prüfen

ratelimitexceeded

HTTP-Status: 429

Du hast das Rate-Limit von 100 Anfragen pro Minute für deinen API-Schlüssel überschritten.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later."
  }
}

Rate-Limit-Header sind in jeder Antwort enthalten:

So behebst du das: - Warte bis zum X-RateLimit-Reset-Zeitstempel, bevor du es erneut versuchst - Füge Verzögerungen zwischen Anfragen in automatisierten Skripten hinzu - Nutze den X-RateLimit-Remaining-Header, um das Limit nicht zu erreichen

internal_error

HTTP-Status: 500

Ein unerwarteter Fehler ist auf dem Server aufgetreten. Die Fehlerdetails werden intern protokolliert, aber aus Sicherheitsgründen nicht in der Antwort offengelegt.

{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred"
  }
}

So behebst du das: - Versuche die Anfrage nach einer kurzen Verzögerung erneut - Wenn der Fehler weiterhin auftritt, kontaktiere den Support mit dem Zeitstempel und dem aufgerufenen Endpunkt

Fehlerbehebung - Kurzreferenz

Verwandte Dokumentation

• API-Übersicht — Authentifizierung, Rate-Limits und Antwortformat
• Instanz-Details abrufen — Aktionsverfügbarkeit vor dem Aufruf prüfen
• Abrechnungs-Endpunkte — Abrechnungsspezifische Fehlerszenarien