Zurück zum Hilfecenter

Schnittstelle: Leitfäden

Fehlerkatalog: jede Antwort richtig deuten

Alle Statuscodes und Fehlercodes der Schnittstelle mit passender Reaktion.

Für wen

Entwicklerinnen und Entwickler.

Voraussetzungen

Bestehender Zugang

Schritt für Schritt

  1. 1

    Fehlerform kennen

    Jeder Fehler antwortet mit demselben Aufbau: `error.code` für die Auswertung durch Ihr System, `error.message` für Menschen.

    Fehler
    {
  "error": {
    "code": "rate_limited",
    "message": "Abfragegrenze erreicht. Bitte später erneut versuchen."
  }
}
  2. 2

    Auf Code statt Text prüfen

    Der Text kann sich ändern und liegt je nach Sprache anders vor. Verzweigen Sie ausschließlich über `error.code`.

    Auswertung
    if (!response.ok) {
  const { error } = await response.json();
  switch (error.code) {
    case "unauthorized":   throw new Error("Schlüssel prüfen");
    case "missing_scope":  throw new Error("Recht in der Verwaltung ergänzen");
    case "rate_limited":   return retryLater(response);
    case "not_found":      return null;
    case "invalid_body":   throw new Error("Eingabe korrigieren: " + error.message);
    default:               throw new Error(error.message);
  }
}
  3. 3

    Wiederholbar und endgültig unterscheiden

    429 und 5xx dürfen wiederholt werden. 401, 403, 404 und 422 sind endgültig — sie brauchen eine Änderung an Schlüssel, Rechten, Pfad oder Inhalt.

  4. 4

    Fehler sichtbar machen

    Protokollieren Sie Statuscode, `error.code` und den Pfad, niemals aber den Schlüssel. In der Verwaltung sehen Sie dieselben Aufrufe von der elyph-Seite.

Statuscodes und Fehlercodes

StatusCodeBedeutungReaktion
401unauthorizedKein, falsch aufgebauter, gesperrter oder abgelaufener Schlüssel.Schlüssel und Kopfzeile prüfen, ggf. neu ausstellen.
403missing_scopeDer Zugang hat das benötigte Recht nicht.Recht in der Verwaltung ergänzen.
403forbidden_fieldEin Feld darf über die Schnittstelle nicht gesetzt werden.Feld weglassen; Vorgang in der Oberfläche erledigen.
403write_not_allowedDer Bereich ist nur lesend verfügbar.Lesenden Weg nutzen.
404unknown_resourceDer Bereich im Pfad existiert nicht.Pfad gegen /v1 prüfen.
404not_foundKennung existiert nicht oder gehört zu einem anderen Mandanten.Kennung prüfen.
422invalid_bodyInhalt fehlerhaft oder Pflichtfeld fehlt.Meldung lesen und Inhalt korrigieren.
422write_failedDie Datenprüfung hat die Änderung abgelehnt.Werte gegen die Referenz prüfen.
429rate_limitedAbfragegrenze erreicht.`retry-after` abwarten, dann wiederholen.

Ergebnis

Ihr System behandelt jeden Fehlerfall bewusst statt pauschal zu wiederholen.

Häufige Stolpersteine

  • Alle Fehler still verschlucken: Fehlende Rechte bleiben dann monatelang unbemerkt.
  • Schlüssel in Protokolldateien schreiben: Ein Auszug in einem Ticket macht ihn öffentlich.

Verwandte Artikel