Fehlercodes

Jede Fehlermeldung sagt, was passiert ist und was hilft. Kein Rätselraten, keine internen Details – dafür eine Vorgangskennung, mit der wir jederzeit nachsehen können.

So sieht eine Fehlerantwort aus

Gleicher Aufbau bei allen Schnittstellen.

Antwort

{
  "ok": false,
  "error": {
    "code": "idempotency_required",
    "message": "Für diesen Aufruf ist ein Vorgangsschlüssel Pflicht.",
    "hint": "Kopf Idempotency-Key mitsenden."
  },
  "meta": {
    "requestId": "req_01J8Z2K9QF",
    "version": "2026-07-01",
    "at": "2026-07-31T09:12:44Z"
  }
}

Alle Codes (9)

Vollständig – weitere Codes gibt es nicht.

Fehlercodes der Ryh API mit Statuscode, Bedeutung und Lösung
Code	Status	Bedeutung	Typische Ursachen	Was hilft	Wiederholen?
unauthorized	401	Der Aufruf war nicht angemeldet.	Token fehlt · Token abgelaufen · Falsche Umgebung	Neues Zugriffstoken anfordern und die Umgebung prüfen.	Nein, erst Ursache beheben
forbidden	403	Der Zugang darf diese Aktion nicht ausführen.	Fehlende Rolle · Betrieb nicht freigegeben	Berechtigungen des Zugangs im Entwicklerportal prüfen.	Nein, erst Ursache beheben
not_found	404	Der angefragte Eintrag existiert nicht.	Falsche Kennung · Eintrag gehört zu einem anderen Betrieb	Kennung und Betrieb im Kopf der Anfrage abgleichen.	Nein, erst Ursache beheben
invalid_request	400	Die Anfrage war unvollständig oder unpassend.	Pflichtfeld fehlt · Falscher Datentyp	Anfrage gegen die veröffentlichte Beschreibung prüfen.	Nein, erst Ursache beheben
capability_denied	409	Die angefragte Fähigkeit ist für diese Verbindung nicht freigegeben.	Fähigkeit nicht gebucht · Verbindung pausiert	Fähigkeit im Integration Hub freischalten lassen.	Nein, erst Ursache beheben
idempotency_conflict	409	Gleicher Vorgangsschlüssel mit abweichendem Inhalt.	Schlüssel wiederverwendet · Inhalt nachträglich geändert	Für jeden neuen Vorgang einen neuen Schlüssel erzeugen.	Nein, erst Ursache beheben
idempotency_required	428	Für diesen Aufruf ist ein Vorgangsschlüssel Pflicht.	Kopf Idempotency-Key fehlt	Vorgangsschlüssel mitsenden.	Nein, erst Ursache beheben
rate_limited	429	Es wurden zu viele Aufrufe in kurzer Zeit gesendet.	Lastspitze · Wiederholung ohne Wartezeit	Wartezeit aus der Antwort beachten und mit wachsendem Abstand erneut versuchen.	Ja, mit wachsendem Abstand
internal	500	Auf unserer Seite ist etwas schiefgelaufen.	Störung im Betrieb	Vorgangskennung notieren, Status Center prüfen und den Developer Support informieren.	Ja, mit wachsendem Abstand

Geltungsbereich

unauthorized

Alle Schnittstellen

forbidden

Alle Schnittstellen

not_found

Alle Schnittstellen

invalid_request

Alle Schnittstellen

capability_denied

Netz und Verbindungen

idempotency_conflict

Verändernde Aufrufe

idempotency_required

Verändernde Aufrufe

rate_limited

Alle Schnittstellen

internal

Alle Schnittstellen

Empfohlene Wiederholung

Nur bei 429 und 500 – alles andere ist ein Fehler in der Anfrage.

TypeScript

const RETRYABLE = new Set(["rate_limited", "internal"]);

export async function callWithRetry<T>(run: () => Promise<T>, attempts = 4): Promise<T> {
  let lastError: unknown;
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await run();
    } catch (error) {
      lastError = error;
      const code = (error as { code?: string }).code ?? "";
      if (!RETRYABLE.has(code)) throw error;
      // Wartezeit verdoppeln, mit kleiner Streuung gegen Lastspitzen
      const wait = 2 ** attempt * 500 + Math.random() * 250;
      await new Promise((resolve) => setTimeout(resolve, wait));
    }
  }
  throw lastError;
}

Antworten enthalten eine Vorgangskennung, aber keine internen Details. Für die Ursachenanalyse genügt uns diese Kennung.