---
title: "Fehlercodes · Alran-Code-Doku"
url: https://alran.dev/de/docs/errors
locale: de
updated: 2026-11-16
---

[Doku](https://alran.dev/de/docs)Referenz

# Fehlercodes

Jeder Fehler, den das Terminal zeigt, trägt eine Nummer. Das ist, was jede bedeutet und was du dagegen tun kannst.

Auf dieser Seite

[Was bedeuten die Fehlercodes des Laufs?](#runtime) [Dieselbe Zahl, verschiedene Bedeutungen](#collide) [Woher die Zahlen kommen](#sources) [Exit-Codes von alran exec](#exec) [Exit-Codes der Konto-Befehle](#account) [Maschinenlesbare Ausgabe](#machine) [Was du zuerst prüfst](#check) [Häufige Fragen](#faq)

## Was bedeuten die Fehlercodes des Laufs? {#runtime}

Wenn eine Antwort scheitert, zeigt das Fehler-Panel der Terminal-Oberfläche den Grund und eine Zeile `Code: <n>`. Diese Zahl ist der Code der Laufzeitumgebung. Dein Prompt bleibt erhalten, du kannst ihn also erneut senden, sobald die Ursache weg ist.

| Code | Name | Was passiert ist | Was du tun kannst |
| `1` | `INVALID_REQUEST` | Die Anfrage war fehlerhaft und wurde abgewiesen, bevor sie lief | Anfrage korrigieren; Code melden, wenn es wiederholt auftritt |
| `2` | `NOT_FOUND` | Die Sitzung, der Agent oder die Datei existiert nicht | Id prüfen, Ressource neu anlegen oder auswählen |
| `3` | `PERMISSION_DENIED` | Dein Konto darf auf diese Ressource nicht zugreifen | Konto, Unternehmen oder Projekt mit der passenden Freigabe nutzen |
| `4` | `CONFLICT` | Die Änderung kollidiert mit etwas, das es schon gibt | Umbenennen oder den Konflikt entfernen, dann erneut senden |
| `5` | `TIMEOUT` | Der Vorgang hat die Zeit überschritten | Erneut senden oder `--timeout` erhöhen |
| `6` | `ABORTED` | Der Lauf wurde abgebrochen | Erneut senden, wenn der Abbruch nicht beabsichtigt war |
| `7` | `RUNTIME_UNAVAILABLE` | Die Laufzeitumgebung war nicht erreichbar | Verbindung und Proxy prüfen, dann erneut senden |
| `8` | `INTERNAL` | Ein nicht eingeordneter interner Fehler | Erneut senden; Code melden, wenn er wiederkehrt |
| `42212` | `USAGE_LIMIT_EXCEEDED` | Dein Konto hat sein Nutzungslimit erreicht | `/usage` prüfen, Guthaben aufladen oder Anbieter wechseln, dann erneut senden |
| `50001` | `INTERNAL_ERROR` | Ein allgemeiner interner Fehler — der Ersatz, wenn die Laufzeitumgebung keinen anderen Code liefert | `/retry` ausführen; Code melden, wenn er wiederkehrt |
| `50110` | `LLM_CREDITS_EXHAUSTED` | Der Anbieter meldet ein leeres Guthaben (HTTP 402) | Guthaben aufladen oder ein anderes Modell nehmen |
| `50111` | `LLM_RATE_LIMITED` | Der Anbieter drosselt Anfragen (HTTP 429) | Einen Moment warten, dann `/retry` ausführen |
| `50112` | `LLM_AUTH_ERROR` | Anbieter oder Gateway haben deine Zugangsdaten abgewiesen (HTTP 401/403) | `alran auth login` ausführen, oder API-Schlüssel und Endpunkt deines eigenen Anbieters korrigieren |
| `50113` | `LLM_UPSTREAM_ERROR` | Der Anbieter hat mit einem Fehler geantwortet | `/retry` ausführen; wenn es wiederholt auftritt, Anbietereinstellungen und Proxy prüfen |
| `50114` | `LLM_MIGRATION_ERROR` | Das Modell wird nicht mehr ausgeliefert | Einen Moment warten und erneut senden, oder mit `alran config model` das Modell wechseln |
| `50150` | `LLM_TPM_RATE_LIMITED` | Deine Tokens pro Minute sind aufgebraucht | Warten, bis das Fenster zurückgesetzt ist, dann `/retry` ausführen |
| `50151` | `LLM_CLUSTER_OVERLOADED` | Der Anbieter-Cluster ist überlastet (HTTP 529) | `/retry` ausführen oder Modell wechseln |
| `50200` | `SAFETY_UNAVAILABLE` | Der Content-Safety-Dienst war nicht erreichbar | Später erneut senden; wenn es wiederholt auftritt, Safety-Pfad und Proxy prüfen |
| `50201` | `SAFETY_SENSITIVE` | Content Safety hat die Nachricht blockiert | Nachricht überarbeiten, bevor du sie erneut sendest |
| `60001` | `CORRUPTED_THINKING` | Der Denkstrom des Modells kam beschädigt an | `/retry` ausführen; Code melden, wenn er wiederkehrt |

Die Codes `1` bis `8` und `50001` sind generisch. Alle anderen benennen den Teil, der gescheitert ist: das Limit, den Anbieter, die Sicherheitsprüfung oder das Modell selbst. Ab `42212` nennt die Zahl den Bereich: `42212` das Nutzungslimit, `501xx` den Anbieter, `502xx` die Sicherheitsprüfung, `60001` das Modell.

## Dieselbe Zahl, verschiedene Bedeutungen {#collide}

Eine Zahl kann in drei Tabellen dieser Seite auftauchen, und sie bedeutet nicht überall dasselbe. `2` ist eine fehlende Sitzung in der Tabelle der Fehlercodes des Laufs, eine kaputte Kommandozeile in `alran exec` und eine fehlende Anmeldung in einem Konto-Befehl; die Tabelle im Abschnitt „Dieselbe Zahl, verschiedene Bedeutungen“ stellt alle drei nebeneinander.

| Zahl | Code der Laufzeitumgebung | Exit-Code von `alran exec` | Exit-Code der Konto-Befehle |
| `1` | `INVALID_REQUEST` | — | Platform oder Gateway haben die Anfrage abgewiesen |
| `2` | `NOT_FOUND` | Die Kommandozeile war falsch | Anmeldung nötig |
| `3` | `PERMISSION_DENIED` | Die Konfiguration ist kaputt | Das Konto ist gedrosselt |
| `4` | `CONFLICT` | Modell oder Laufzeitumgebung schlugen fehl | Die Platform ist nicht erreichbar |
| `5` | `TIMEOUT` | — | Das Guthaben deckt es nicht |
| `6` | `ABORTED` | Der Lauf hat `--timeout` erreicht | — |
| `7` | `RUNTIME_UNAVAILABLE` | Der Lauf hat `--max-steps` erreicht | — |
| `8` | `INTERNAL` | — | — |

Die Exit-Codes `70`, `130` und `141` gehören nur zu `alran exec`.

Schau eine Zahl in der Tabelle nach, zu der Stelle gehört, an der du sie gesehen hast: im Fehler-Panel der Terminal-Oberfläche ist sie ein Code der Laufzeitumgebung, im Prozessstatus ein Exit-Code.

Umgekehrt kann ein Ereignis zwei Zahlen haben: ein Timeout ist Code `5` der Laufzeitumgebung und Exit-Code `6`, ein Abbruch ist Code `6` und Exit-Code `130`.

## Woher die Zahlen kommen {#sources}

Drei Parteien sind im Spiel. Dein Konto und dein Guthaben liegen auf der Ottili AI Platform. Das Gateway leitet die Anfrage weiter und prüft bei Werk das Guthaben; bei Claude schickt es sie mit deinem eigenen Anthropic-Schlüssel weiter. Der Anbieter ist der Modellhersteller dahinter — Ottili Werk, Claude oder der, den du selbst mitgebracht hast ([eigener Anbieter](https://alran.dev/de/docs/byok)).

Anbieter und Gateway melden eigene Codes. Alran Code bildet sie auf die Zahlen oben ab, damit die Tabelle gleich bleibt, egal welcher Anbieter dahintersteht.

| Code des Anbieters | Wird zu | Bedeutung |
| `1400010161` | `50110` | Das Guthaben deckt die Anfrage nicht |
| `2056` | `42212` | Das Nutzungslimit ist erreicht |
| `2067` | `42212` | Das Token-Plan-Limit ist erreicht und automatische Guthabennutzung ist aus — automatische Guthabennutzung wieder einschalten oder den Plan erhöhen |
| `2045`, `2046`, `2047`, `1039`, `1041` | `50150` | Der Anbieter drosselt Tokens pro Minute |

Wenn einer davon in einem Log auftaucht, schau die Zahl nach, auf die er abgebildet wird.

## Exit-Codes von alran exec {#exec}

`alran exec` endet mit einer Zahl, an der dein Skript verzweigen kann. Exit-Code `4` ist ein Sammelcode: er fasst jeden Fehler von Modell oder Laufzeitumgebung zusammen, und die `message` der JSON-Ausgabe sagt, welcher es war.

| Code | Bedeutung | Was du tun kannst |
| `0` | Der Lauf war erfolgreich | Nichts |
| `2` | Die Kommandozeile war falsch: fehlender Prompt, unbekanntes Flag oder unbrauchbares Modell | Kommandozeile korrigieren |
| `3` | Die Konfiguration ist kaputt | Alran öffnen und `/doctor` ausführen |
| `4` | Der Lauf startete, aber Modell oder Laufzeitumgebung schlugen fehl | Das `error`-Objekt der JSON-Ausgabe unten lesen: die `message` sagt, was schiefging, der `code` benennt den Fehler |
| `6` | Der Lauf hat `--timeout` erreicht | `--timeout` erhöhen oder die Aufgabe kleiner machen |
| `7` | Der Lauf hat `--max-steps` erreicht | `--max-steps` erhöhen oder die Aufgabe eingrenzen |
| `70` | Ein interner Fehler | Mit `alran --version` melden |
| `130` | Der Lauf wurde abgebrochen | Nichts, du hast ihn gestoppt |
| `141` | Die Ausgabe-Pipe wurde vorzeitig geschlossen, zum Beispiel von `head` | Die Ausgabe auslaufen lassen oder in eine Datei schreiben |

Die Codes `1` und `5` kommen hier nicht vor.

## Exit-Codes der Konto-Befehle {#account}

`alran auth`, `alran config`, `alran models`, `alran usage` und `alran billing` nutzen einen anderen Satz:

| Code | Bedeutung | Was du tun kannst |
| `0` | Der Befehl war erfolgreich | Nichts |
| `1` | Platform oder Gateway haben die Anfrage abgewiesen | Meldung lesen, dann Konto und Modell prüfen |
| `2` | Anmeldung nötig | `alran auth login` ausführen oder `ALRAN_API_KEY` setzen |
| `3` | Das Konto ist gedrosselt | So lange warten, wie die Meldung sagt |
| `4` | Platform oder Gateway waren nicht erreichbar | Verbindung und Proxy prüfen, dann erneut versuchen |
| `5` | Dein Guthaben deckt die Anfrage nicht, oder Claude hat keinen funktionierenden Anthropic-Schlüssel | Guthaben aufladen oder Anthropic-Schlüssel hinterlegen, auf der [Ottili AI Platform](https://ai.ottili.one) |

Die beiden Sätze teilen sich die Zahlen `0`, `2`, `3` und `4`, meinen aber verschiedene Dinge. `2` ist in `alran exec` eine kaputte Kommandozeile und in einem Konto-Befehl eine fehlende Anmeldung. Verzweige nach dem ausgeführten Befehl, nie nach der Zahl allein.

## Maschinenlesbare Ausgabe {#machine}

`alran exec --output-format json` gibt ein JSON-Dokument aus. Scheitert der Lauf, trägt es ein `error`-Objekt:

```json
{
  "schemaVersion": 1,
  "type": "exec.result",
  "status": "failed",
  "error": {
    "category": "runtime",
    "code": "REVIEW_RESULT_MISSING",
    "message": "Runtime completed without a validated code review result.",
    "retryable": true
  },
  "durationMs": 1234
}
```

Das `category` sagt, was für eine Art von Fehler es war (`config`, `runtime`, `internal`), und `retryable`, ob ein erneutes Senden helfen kann. Der Exit-Code des Prozesses folgt trotzdem der Tabelle im Abschnitt „Exit-Codes von `alran exec`“.

Der `code` in dieser Ausgabe ist ein **Name**, keine Zahl, und er ist optional. Die Namen, die der Runner selbst benutzt:

| Name | Was er bedeutet |
| `REVIEW_RESULT_MISSING` | Die Laufzeitumgebung endete ohne Code-Review-Ergebnis |
| `REVIEW_RESULT_INVALID` | Die Laufzeitumgebung lieferte ein ungültiges Code-Review-Ergebnis |
| `INTERACTION_NOT_AVAILABLE` | Die Laufzeitumgebung hat eine Frage gestellt, und `alran exec` kann nicht fragen |
| `STRUCTURED_OUTPUT_INVALID` | Die Antwort passte nicht zum verlangten Format |
| `RUNTIME_SHUTDOWN_FAILED` | Die Laufzeitumgebung wurde nicht sauber beendet |
| `OUTPUT_LAST_MESSAGE_WRITE_FAILED` | Die letzte Nachricht konnte nicht auf die Platte geschrieben werden |

Ein fehlgeschlagener Modellaufruf trägt oft gar keinen `code`, nur die Meldung des Anbieters. Lies die `message` für das, was passiert ist, und den `code`, um einen Fehler des Runners zu erkennen.

Die Zahlen der ersten Tabelle stehen nicht in dieser Ausgabe. Sie gehören zum Fehler-Panel der Terminal-Oberfläche. Ein Skript muss mit `message` und dem Namen im `code` arbeiten.

Führt eine Testumgebung die Terminal-Oberfläche, kann sie die Zahl trotzdem mitnehmen: `ALRAN_TUI_RESULT_PATH` auf eine Datei setzen, dann wird jeder Zug als eine JSON-Zeile angehängt, mit der Zahl im Feld `code` des Fehlers. Dort ist der `code` **die** Zahl — dasselbe Feld trägt in der JSON-Ausgabe oben einen Namen und in dieser Datei eine Zahl.

## Was du zuerst prüfst {#check}

| Symptom | Erster Schritt |
| Ein Modellaufruf scheitert | `/status` für Konto und Modell, `/usage` für das Guthaben |
| Die Konfiguration sieht falsch aus | `/doctor` |
| Ein Lauf in der CI scheitert | die Exit-Code-Tabelle von `alran exec` oben, dann das `error`-Objekt der JSON-Ausgabe |
| Etwas wird nicht gefunden | Ids prüfen: die Sitzungen mit `alran --session` durchsehen |

Immer noch nicht weiter? Die [Fehlerbehebung](https://alran.dev/de/docs/troubleshooting) listet die üblichen Verdächtigen. Für einen [Fehlerbericht](https://alran.dev/de/docs/troubleshooting#report) braucht es dein `alran --version`, die genutzte Oberfläche (TUI, `exec`, ACP) und eine minimale Reproduktion.

## Häufige Fragen {#faq}

Was bedeuten die Fehlercodes des Laufs?

Wenn eine Antwort scheitert, zeigt das Fehler-Panel der Terminal-Oberfläche den Grund und eine Zeile mit der Codenummer. Die Codes 1 bis 8 und 50001 sind generisch, alle anderen benennen den Teil, der gescheitert ist: 42212 das Nutzungslimit, 501xx den Anbieter, 502xx die Sicherheitsprüfung und 60001 das Modell.

Warum bedeutet Exit-Code 2 nicht immer dasselbe?

Dieselbe Zahl taucht in drei Tabellen auf: im Fehler-Panel der Terminal-Oberfläche ist sie ein Code der Laufzeitumgebung, im Prozessstatus ein Exit-Code. Exit-Code 2 ist in alran exec eine kaputte Kommandozeile und in einem Konto-Befehl eine fehlende Anmeldung, also verzweigst du nach dem ausgeführten Befehl und nie nach der Zahl allein.

Wie bekomme ich eine maschinenlesbare Ausgabe von alran exec?

alran exec --output-format json gibt ein JSON-Dokument aus, und wenn der Lauf scheitert, trägt es ein error-Objekt mit category, code und message. Der code ist ein Name, keine Zahl, und er ist optional, während der Exit-Code des Prozesses der Exit-Code-Tabelle von alran exec folgt.

[ZurückKonfiguration und Daten](https://alran.dev/de/docs/config) [WeiterFehlerbehebung](https://alran.dev/de/docs/troubleshooting)
