# Audio transkribieren

Wandelt Sprache in Text um. Audio als JSON mit Base64 in `input_audio` (OpenRouter-Format)
oder als `multipart/form-data` mit einem `file`-Teil (OpenAI-Format, wie von dessen SDKs gesendet)
übermitteln. Antwort wie bei OpenRouter: `text` und `usage` mit Kosten in EUR, zusätzlich
`language`, `duration` und `segments` bei `response_format: verbose_json`.

Das Gateway wählt unter Berücksichtigung der `provider`-Präferenzen einen europäischen Anbieter
des Modells und versucht bei einem Fehler den nächsten. Ob der Anbieter einen Upload oder
Base64-JSON erhält, bestimmt seine Konfiguration, nicht die Anfrage. Der Body wird vor jedem
Anbieteraufruf vollständig validiert; alle Probleme stehen in `error.metadata.issues`. Audio
per URL (`input_audio.url`, `source_url`), Sprecherkennzeichnungen (`diarize`) und `keyterms`
werden von den Anbietern dieses Gateways nicht unterstützt und führen zu 400.

Administrative PII-Anforderungen werden für jede tatsächliche Route einschließlich Fallbacks
und Wiederholungen geprüft. Dieser Endpunkt kann seine Eingabe nicht schwärzen: Eine passende
Anforderung liefert vor Anbieter-I/O `invalid_parameter` mit einem `not_available`-Problem
bei `$.model`.

`POST https://api.tokenlane.de/v1/audio/transcriptions`

## Authentifizierung

[
  [
    {
      "name": "Authorization",
      "description": "API-Key als Bearer-Token im Header `Authorization`: `Authorization: Bearer sk-tl-v1-…`. Bestehende `sk-eu-`-Keys bleiben gültig. Fehlende, unbekannte oder abgelaufene Keys erhalten 401 `authentication`.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

## curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/audio/transcriptions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}'
```

## node

```node
const response = await fetch("https://api.tokenlane.de/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}`,
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

body = (r'''{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}''').encode("utf-8")

request = urllib.request.Request(
    "https://api.tokenlane.de/v1/audio/transcriptions",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Content-Type": "application/json",
    },
    data=body,
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}`,
});
console.log(await response.text());
```

## Header: x-session-id (optional)

Groups the generation into a session, immediately available from GET /v1/sessions/{id}. Use 1 to 256 ASCII letters, digits, '-', '_', '.' or ':'; an ID cannot consist only of dots. A non-null session_id in JSON or multipart takes precedence. Never sent to the provider.

### s0: string | null

{}

## Header: Idempotency-Key (optional)

Ausdrückliches Opt-in zur verschlüsselten Antwortwiederholung über alle Gateway-Knoten. Ein Wert aus 1 bis 255 druckbaren ASCII-Zeichen pro logischem Vorgang, begrenzt auf die Identität dieses API-Keys. Methode, Pfad und normalisierten Body unverändert wiederholen. Abgeschlossene Antworten bleiben höchstens zehn Minuten verfügbar; eine Wiederholung ist kostenlos und erzeugt keine neue Generierung. Abweichender Inhalt oder eine nicht sicher wiederholbare Antwort ergibt 409. Eine erfolgreiche Wiederholung enthält Idempotent-Replayed: true und erhält die ursprünglichen Request- und Generation-IDs. Siehe /docs/guides/idempotency.

## Anfrageinhalt: application/json

```json
{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "mistralai/voxtral-mini-transcribe-3-0"
}
```

### s4: object

Zu transkribierendes Audio als JSON im OpenRouter-Format. Die Audiodaten stehen Base64-kodiert in `input_audio`.

Vor jedem Provider-Aufruf wird der Anfrageinhalt validiert. Alle Probleme stehen in `error.metadata.issues`. Dekodiertes Audio darf höchstens 50 MiB groß sein und muss in den 50-MiB-Anfrageinhalt passen. Mit Base64 passen etwa 37 MiB Audio hinein. Größere Dateien als `multipart/form-data` hochladen. Unbekannte Parameter werden ignoriert und in `x-ignored-params` genannt.

{}

```json
{
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "format": "wav"
  },
  "language": "de",
  "model": "openai/whisper-large-v3"
}
```

- diarize (optional): s240

### s240: boolean

Sprecherkennzeichnungen. Die Provider dieses Gateways unterstützen sie nicht. `true` scheitert mit 400 `invalid_parameter`.

{}

```json
false
```

- input_audio (Pflichtfeld): s241

### s241: anyOf

Audio als `{"data": <base64>, "format": <format>}`. Formate: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav, webm. `{"url": …}`, bei dem der Provider das Audio herunterlädt, wird von den Providern dieses Gateways nicht unterstützt und scheitert mit 400 `invalid_parameter`.

{}

anyOf: s201

### s201: object

Audio als Base64.

{"additionalProperties":"false"}

```json
{
  "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
  "format": "wav"
}
```

- data (Pflichtfeld): s982

### s982: string

Base64-kodierte Audiodatei mit Standard- oder URL-sicherem Alphabet, ohne Daten-URL-Präfix.

{}

- format (Pflichtfeld): s983

### s983: string

Audioformat: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav oder webm. Groß- und Kleinschreibung ist beliebig.

{"pattern":"\"^[a-zA-Z0-9][a-zA-Z0-9+._-]{0,15}$\""}

```json
"wav"
```

anyOf: s202

### s202: object

Audio, das der Provider herunterlädt. Die Provider dieses Gateways unterstützen dies nicht.

{"additionalProperties":"false"}

```json
{
  "format": "mp3",
  "url": "https://example.com/meeting.mp3"
}
```

- format (optional): s984

### s984: string

Format der Audiodaten unter der URL.

{"pattern":"\"^[a-zA-Z0-9][a-zA-Z0-9+._-]{0,15}$\""}

```json
"mp3"
```

- url (Pflichtfeld): s985

### s985: string

URL der Audiodatei. Scheitert mit 400 `invalid_parameter`.

uri

{"maxLength":"8000"}

- keyterms (optional): s242

### s242: array

Begriffe zur Beeinflussung der Erkennung. Von den Providern dieses Gateways nicht unterstützt. Eine nicht leere Liste scheitert mit 400 `invalid_parameter`. Solche Begriffe unter `prompt` angeben.

{}

### s7: string

{}

- language (optional): s243

### s243: string

Audiosprache als ISO-639-1-Code, beispielsweise `de`. Ohne Angabe wird sie erkannt.

{}

```json
"de"
```

- metadata (optional): s244

### s244: any

Lokale Metadaten: höchstens 16 Zeichenkettenpaare, Schlüssel mit 1 bis 64 und Werte mit 0 bis 512 Zeichen.

{}

- model (Pflichtfeld): s245

### s245: string

Transkriptionsmodell mit derselben ID wie bei OpenRouter oder einem Gateway-Alias. Modelle ohne Audiotranskription scheitern mit 404 `no_endpoint`. Eine unbekannte ID scheitert mit 400 `model_not_found` und einem Vorschlag unter `remedy_hint`.

{}

```json
"openai/whisper-large-v3"
```

- prompt (optional): s246

### s246: string

Text zur Steuerung der Transkription, beispielsweise Namensschreibweisen oder der vorherige Teil einer längeren Aufnahme. Wird unverändert an den Provider weitergegeben.

{}

```json
"Prozesshub, dpa"
```

- provider (optional): s247

### s247: object

Routing-Einstellungen wie bei Chat Completions: `only`, `ignore`, `order`, `allow_fallbacks`, `sort` und `max_price`. Werden nie an den Provider gesendet.

{}

- response_format (optional): s248

### s248: string

`json` ist der Standard und liefert `text` und `usage`. `verbose_json` ergänzt `language`, `duration` und zeitgestempelte `segments`.

"json", "verbose_json"

{}

```json
"json"
```

- session_id (optional): s249

### s249: string | null

Groups related requests in generation records and `GET /v1/sessions/{id}`. Use 1 to
256 ASCII letters, digits, `-`, `_`, `.` or `:`; not only dots. A non-null body value
takes precedence over `x-session-id`. Never sent to the provider.

{"minLength":"1","maxLength":"256"}

```json
"session-1234"
```

- temperature (optional): s250

### s250: number

Sampling-Temperatur von 0 bis 1.

double

{}

```json
0
```

- timestamp_granularities (optional): s251

### s251: array

Zeitstempeldetail bei `verbose_json`: `segment` und für ein Array `words` zusätzlich `word`.

{}

### s215: string

Eine Zeitstempel-Detailstufe von `verbose_json`.

"word", "segment"

{}

```json
"segment"
```

- trace (optional): s252

### s252: object

Ablaufmetadaten zur Beobachtbarkeit. Werden nie an den Provider gesendet.

{}

- user (optional): s253

### s253: string

Kennung des Endnutzers, die lokal gespeichert wird. Nur ein mandantenbezogener Hash darf an eine Route übermittelt werden, die `user` ausdrücklich unterstützt.

{"maxLength":"256"}

```json
"user-1234"
```

## Anfrageinhalt: multipart/form-data

```json
{
  "file": "meeting.mp3",
  "language": "de",
  "model": "openai/whisper-large-v3"
}
```

### s5: object

Zu transkribierendes Audio als Datei-Upload, wie ihn die OpenAI-SDKs senden.

{}

```json
{
  "file": "meeting.mp3",
  "language": "de",
  "model": "openai/whisper-large-v3"
}
```

- diarize (optional): s254

### s254: boolean

Sprecherkennzeichnungen. `true` scheitert mit 400, da die Provider dieses Gateways sie nicht unterstützen.

{}

- file (optional): s255

### s255: string

Die erforderliche Audiodatei, höchstens 50 MiB. `source_url` wird nicht unterstützt. Das Format wird aus Dateiendung oder Content-Type des Parts ermittelt: aac, flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, opus, wav oder webm.

binary

{}

- keyterms[] (optional): s256

### s256: array

Begriffe zur Beeinflussung der Erkennung, ein Teil je Begriff. Von den Providern dieses Gateways nicht unterstützt (400).

{}

- language (optional): s257

### s257: string

Audiosprache als ISO-639-1-Code. Ohne Angabe wird sie erkannt.

{}

- metadata (optional): s258

### s258: string | null

Lokale Metadaten als JSON-Objekt mit höchstens 16 Zeichenkettenpaaren, Schlüsseln mit 1 bis 64 und Werten mit 0 bis 512 Zeichen. Sie werden nie an den Provider übermittelt.

{}

```json
"{\"workflow\":\"support\"}"
```

- model (Pflichtfeld): s259

### s259: string

Transkriptionsmodell wie in der JSON-Form.

{}

```json
"openai/whisper-large-v3"
```

- prompt (optional): s260

### s260: string

Text zur Steuerung der Transkription.

{}

- provider (optional): s261

### s261: string

Routing-Einstellungen als JSON-kodiertes Objekt.

{}

- response_format (optional): s262

### s262: string

`json` als Standard oder `verbose_json`.

"json", "verbose_json"

{}

```json
"json"
```

- session_id (optional): s263

### s263: string

Groups related requests in generation records and `GET /v1/sessions/{id}`. Use 1 to
256 ASCII letters, digits, `-`, `_`, `.` or `:`; not only dots. This form field takes
precedence over `x-session-id`. Never sent to the provider.

{"minLength":"1","maxLength":"256"}

- source_url (optional): s264

### s264: string

Audio-URL zum Herunterladen durch den Provider. Von den Providern dieses Gateways nicht unterstützt (400). Stattdessen die Datei hochladen.

uri

{}

- temperature (optional): s265

### s265: number

Sampling-Temperatur von 0 bis 1.

{}

- timestamp_granularities[] (optional): s266

### s266: array

Zeitstempeldetail bei `verbose_json`, ein Teil je Wert.

{}

Eine Zeitstempel-Detailstufe von `verbose_json`.

- trace (optional): s267

### s267: string

Ablaufmetadaten als JSON-kodiertes Objekt. Werden nie an den Provider gesendet.

{}

- user (optional): s268

### s268: string

Kennung des Endnutzers, die lokal gespeichert wird. Nur ein mandantenbezogener Hash darf an eine Route übermittelt werden, die `user` ausdrücklich unterstützt.

{"maxLength":"256"}

## Antwort 200: application/json

Transkript mit den Provider-Zählwerten und EUR-Kosten unter `usage`.

```json
{
  "text": "Guten Tag, hier ist die Zusammenfassung der Sitzung.",
  "usage": {
    "cost": 0.001,
    "currency": "EUR",
    "is_byok": false,
    "seconds": 9.2
  }
}
```

### s6: object

Transkript im OpenRouter-Format mit EUR-Kosten.

{}

```json
{
  "text": "Guten Tag, hier ist die Zusammenfassung der Sitzung.",
  "usage": {
    "cost": 0.001,
    "currency": "EUR",
    "is_byok": false,
    "seconds": 9.2
  }
}
```

- text (Pflichtfeld): s269

### s269: string

Transkribierter Text.

{}

```json
"Guten Tag, hier ist die Zusammenfassung der Sitzung."
```

- usage (optional): s270

### s270: object

Provider-Zählwerte und EUR-Kosten, sofern Daten gemeldet wurden, auf die die Modellpreise anwendbar sind. Andernfalls fehlt `cost`, statt 0 zu sein.

{}

```json
{
  "cost": 0.001,
  "currency": "EUR",
  "is_byok": false,
  "seconds": 9.2
}
```

- cost (optional): s1003

### s1003: number

Kosten der Anfrage in EUR. Tokens werden zu den Tokenpreisen des Modells berechnet, Audio zum Sekundenpreis. Angefangene Sekunden zählen vollständig.

double

{}

```json
0.001
```

- input_tokens (optional): s1004

### s1004: integer

Eingabetokens, sofern der Provider Tokens zählt.

int64

{"minimum":"0"}

```json
83
```

- output_tokens (optional): s1005

### s1005: integer

Ausgabetokens, sofern der Provider Tokens zählt.

int64

{"minimum":"0"}

```json
30
```

- seconds (optional): s1006

### s1006: number

Audiodauer in Sekunden, sofern der Provider sie meldet.

double

{}

```json
9.2
```

- total_tokens (optional): s1007

### s1007: integer

Eingabe- und Ausgabetokens zusammen.

int64

{"minimum":"0"}

```json
113
```

- * (optional): s1008

### s1008: any

Öffentliche Felder: `currency` (immer `EUR`), `is_byok` und exakte `cost_details`. Unbekannte Provider-Nutzungsfelder werden entfernt.

{}

- * (optional): s271

### s271: any

Öffentliche OpenRouter-Transkriptionsfelder, beispielsweise `language`, `duration`, `segments` und `words` bei `verbose_json`. Eine optionale Erweiterung `id` wird weggelassen, wenn sie keine nicht leere Zeichenkette mit höchstens 128 Bytes ist oder die Zugangsdaten dieses Providers enthält, auch in kodierter Form.

{}

## Antwort 400: application/json

Erkannte Upstream-Ablehnungen mit 400 oder 422 ergeben Client-Fehler ohne sinnvollen erneuten Versuch und mit sicheren öffentlichen Feldpfaden. Ungültige Anfrage: fehlerhaftes JSON oder ein fehlerhaftes Formular (`invalid_request`), ungültige Felder wie fehlendes oder nicht als Base64 vorliegendes Audio, ein nicht unterstütztes Audioformat oder nicht unterstützte Optionen mit allen Problemen unter `issues` (`invalid_parameter`), oder eine unbekannte Modell-ID mit Vorschlag unter `remedy_hint` (`model_not_found`).

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

### s3: object

Jede Antwort mit HTTP-Status ab 400 hat diese Struktur im Fehlerformat von OpenRouter. Alle Gateway-Erweiterungen stehen unter `error.metadata`, damit OpenRouter-Clients keine unbekannte äußere Struktur erhalten. Der Abschnitt „Fehler“ in der Einführung nennt alle Fehlertypen.

{}

```json
{
  "error": {
    "code": 400,
    "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
    "metadata": {
      "docs_url": "/docs#description/model-not-found",
      "issues": [
        {
          "code": "unknown_model",
          "message": "deepseek/deepseek-v4.1-flsh is not a valid model ID",
          "path": "$.model"
        }
      ],
      "remedy_hint": "Did you mean deepseek/deepseek-v4.1-flash?",
      "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
      "retryable": false,
      "type": "model_not_found"
    }
  },
  "user_id": "org_01k7tm2c4e6g8j0k2m4p6r8t0v"
}
```

- error (Pflichtfeld): s238

### s238: object

Fehlerbeschreibung.

{}

```json
{
  "code": 400,
  "message": "temperature must be at most 2, got 5 (and 1 more)",
  "metadata": {
    "docs_url": "/docs#description/invalid-parameter",
    "issues": [
      {
        "code": "out_of_range",
        "message": "temperature must be at most 2, got 5",
        "path": "$.temperature"
      },
      {
        "code": "invalid_value",
        "message": "messages[1].role must be one of system, developer, user, assistant, tool, got \"bot\"",
        "path": "$.messages[1].role"
      }
    ],
    "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
    "retryable": false,
    "type": "invalid_parameter"
  }
}
```

- code (Pflichtfeld): s633

### s633: integer

HTTP-Status der Antwort als Zahl.

int32

{"minimum":"0"}

```json
400
```

- message (Pflichtfeld): s634

### s634: string

Fehlerbeschreibung auf Englisch. Bei mehreren Problemen werden das erste und die Anzahl weiterer genannt. Alle stehen unter `metadata.issues`. Der Text kann sich ändern. Im Code stattdessen `metadata.type` auswerten.

{}

```json
"temperature must be at most 2, got 5"
```

- metadata (optional): s635

### s635: object

Maschinenlesbare Details: Fehlertyp, Anfrage-ID, alle Probleme, ein Lösungsvorschlag und bei Provider-Fehlern der betroffene Provider. Bei Gateway-Fehlern immer vorhanden.

{}

```json
{
  "docs_url": "/docs#description/rate-limited",
  "provider_error": {
    "category": "rate_limited",
    "provider_name": "deepinfra",
    "retry_after": 2,
    "retryable": true,
    "status": 429
  },
  "provider_name": "deepinfra",
  "remedy_hint": "Retry after the Retry-After interval, or allow fallbacks to other providers (provider.allow_fallbacks).",
  "request_id": "req_01k7tm9qz3f5c8x2v6b4n0m7hd",
  "retry_after": 2,
  "retryable": true,
  "type": "rate_limited"
}
```

- available_providers (optional): s639

### s639: array

Provider, die das Modell anbieten, wenn `provider.only` alle ausgeschlossen hat.

{}

```json
[
  "deepinfra",
  "open-inference"
]
```

- docs_url (Pflichtfeld): s640

### s640: string

Link zum Abschnitt dieses Fehlertyps in der Dokumentation.

{}

```json
"/docs#description/model-not-found"
```

- failed_routing_step (optional): s641

### s641: string

Routing-Schritt, nach dem keine Route übrig blieb. Nur bei Routing-Fehlern.

{}

```json
"Filter by Max Price"
```

- issues (optional): s642

### s642: array

Alle erkannten Probleme der Anfrage, damit sie gemeinsam behoben werden können. Höchstens 20 Einträge. Bei Routing-Fehlern ein Eintrag je ausgeschlossener Route, bei `no_provider_available` einer je fehlgeschlagenem Versuch.

{}

### s123: object

Ein Anfrageproblem, ein Ausschlussgrund einer Route oder ein fehlgeschlagener Versuch.

{}

```json
{
  "code": "invalid_url",
  "message": "messages[2].content[0].image_url.url must be an http(s) URL or a base64 data URL",
  "path": "$.messages[2].content[0].image_url.url"
}
```

- code (Pflichtfeld): s636

### s636: string

Art des Problems. Für Programme stabil.

"required", "invalid_type", "invalid_value", "out_of_range", "empty", "invalid_url", "invalid_base64", "unsupported_media_type", "media_type_mismatch", "media_too_large", "too_many_media", "unsupported_media_transport", "media_fetch_failed", "unknown_tool", "unknown_model", "not_available", "not_allowed", "route_excluded", "bridge_failed", "provider_failed"

{}

```json
"out_of_range"
```

- message (Pflichtfeld): s637

### s637: string

Problembeschreibung auf Englisch mit dem Feld und, sofern kurz, dem gesendeten Wert.

{}

```json
"temperature must be at most 2, got 5"
```

- path (Pflichtfeld): s638

### s638: string

Position des Problems: JSONPath des Felds im Anfrageinhalt, beispielsweise `$.messages[2].content[0].image_url.url`, oder `query.<name>` bei einem Abfrageparameter.

{}

```json
"$.temperature"
```

- provider_error (optional): s643

### s643: oneOf

Sichere Provider-Diagnosen, einheitlich für HTTP-Fehler und finale Stream-Ereignisse.

{}

oneOf: s1158

### s1158: object

Provider-Diagnosen ohne vom Provider verfassten Text. HTTP-Fehler und finale SSE-Fehler verwenden dieselbe Struktur. Beliebige Upstream-Meldungen und Metadaten werden verworfen.

{}

```json
{
  "category": "rate_limited",
  "provider_name": "deepinfra",
  "retry_after": 2,
  "retryable": true,
  "status": 429
}
```

- category (Pflichtfeld): s1299

### s1299: string

Gateway-Klassifizierung anhand von HTTP-Status und erkannten Dialektkennungen.

"rate_limited", "overloaded", "invalid_request", "context_length", "content_filtered", "authentication", "billing", "timeout", "unavailable", "unknown"

{}

```json
"rate_limited"
```

- code (optional): s1300

### s1300: string

Exakte Kennung aus der festen Liste des konfigurierten Dialekts. Beliebige andere Werte werden entfernt.

{}

```json
"rate_limit_exceeded"
```

- provider_name (Pflichtfeld): s1301

### s1301: string

Konfigurierter Provider-Name. Nie ein Name aus dem Upstream-Antwortinhalt.

{}

```json
"deepinfra"
```

- retry_after (optional): s1302

### s1302: integer

Begrenzte Wartezeit in Sekunden aus dem Upstream-Header Retry-After, sofern vorhanden und numerisch.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s1303

### s1303: boolean

Ob der klassifizierte Fehler vorübergehend sein kann. Bei unbekannten Fehlern wird ein sinnvoller erneuter Versuch nicht zugesichert.

{}

- status (optional): s1304

### s1304: integer

Tatsächlich vom Upstream empfangener HTTP-Status, einschließlich 200 bei nativen Fehlern. Fehlt, wenn kein HTTP-Status verfügbar ist.

int32

{"minimum":"0"}

```json
429
```

oneOf: s588

### s588: null

{}

- provider_name (optional): s644

### s644: string

Fehlgeschlagener Provider wie im Antwortfeld `provider`. Nur bei Provider-Fehlern.

{}

```json
"deepinfra"
```

- raw (optional): s645

### s645: string

Reserviertes Feld für OpenRouter-Kompatibilität. Das Gateway befüllt es nie. Freier Provider-Text wird bewusst nicht ausgegeben. Stattdessen provider_error verwenden.

{}

```json
""
```

- remedy_hint (optional): s646

### s646: string

Ein konkreter Lösungsvorschlag, beispielsweise die ähnlichste Modell-ID bei einem Tippfehler.

{}

```json
"Did you mean deepseek/deepseek-v4.1-flash?"
```

- request_id (Pflichtfeld): s647

### s647: string

Anfrage-ID. Identisch mit dem Antwortheader `x-request-id`. Diese ID bei Supportanfragen angeben.

{}

```json
"req_01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- requested_providers (optional): s648

### s648: array

Unter `provider.only` genannte Provider, wenn dadurch alle Routen ausgeschlossen wurden.

{}

```json
[
  "scaleway"
]
```

- retry_after (optional): s649

### s649: integer

Wartezeit vor einem erneuten Versuch in Sekunden. Wird bei 429 und 503 auch als Header `Retry-After` gesendet.

int64

{"minimum":"0"}

```json
2
```

- retryable (Pflichtfeld): s650

### s650: boolean

Ob dieselbe unveränderte Anfrage bei einem erneuten Versuch erfolgreich sein kann, beispielsweise nach einer Zeitüberschreitung oder einem Anfragelimit. Im Gegensatz zu Fehlern, die eine geänderte Anfrage erfordern.

{}

- routing_funnel (optional): s651

### s651: array

Eingrenzung der Provider durch das Routing. Jeder Schritt nennt die Anzahl verbleibender Routen. Nur bei Routing-Fehlern, im selben Format wie bei OpenRouter.

{}

### s200: object

Ein Routing-Schritt wie unter `routing_funnel` von OpenRouter.

{}

```json
{
  "endpoint_count": 0,
  "reason": "provider.max_price",
  "step": "Filter by Max Price"
}
```

- endpoint_count (Pflichtfeld): s979

### s979: integer

Anzahl der nach diesem Schritt verbleibenden Routen beziehungsweise Modell-Provider.

{"minimum":"0"}

```json
2
```

- reason (optional): s980

### s980: string

Anfragefeld, nach dem der Schritt gefiltert hat.

{}

```json
"provider.only"
```

- step (Pflichtfeld): s981

### s981: string

Name des Schritts wie bei OpenRouter.

{}

```json
"Initial Endpoints"
```

- type (Pflichtfeld): s652

### s652: string

Stabiler Fehlertyp für die Auswertung im Code. Siehe „Fehler“ in der Einführung. Meldungen können sich ändern, der Typ bleibt stabil.

"invalid_request", "invalid_parameter", "unsupported_parameter", "context_length_exceeded", "authentication", "insufficient_credits", "workspace_budget_exceeded", "permission_denied", "moderation", "model_not_found", "no_endpoint", "not_found", "method_not_allowed", "timeout", "payload_too_large", "media_fetch_failed", "rate_limited", "provider_error", "idempotency_conflict", "idempotency_in_progress", "idempotency_unavailable", "provider_invalid_response", "no_provider_available", "byok_invalid_credential", "byok_rate_limited", "byok_unavailable", "feature_unavailable", "internal"

{}

```json
"invalid_parameter"
```

- user_id (optional): s239

### s239: string | null

Organisation des API-Keys, sofern der Key erkannt wurde.

{}

```json
"org_01k7tm2c4e6g8j0k2m4p6r8t0v"
```

## Antwort 401: application/json

API-Key fehlt, ist ungültig oder abgelaufen (`authentication`).

## Antwort 402: application/json

Das Ausgabenlimit des API-Schlüssels, das Arbeitsbereichsbudget (`workspace_budget_exceeded`) oder das vorausbezahlte Organisationsguthaben deckt die geschätzte Reservierung einschließlich Gebühren, Medien und gleichzeitiger Reservierungen nicht (`insufficient_credits` bei Schlüssel und Organisation). Ohne Reservierung beginnt kein kostenpflichtiger Upstream-Aufruf.

## Antwort 403: application/json

Die Richtlinie der Organisation, des Arbeitsbereichs oder des Schlüssels erlaubt das Modell nicht (`permission_denied`); `remedy_hint` nennt die erlaubten Modelle

## Antwort 404: application/json

Das Modell existiert, aber keiner seiner Provider passt zur Anfrage: keine Audiotranskription oder Ausschluss aller Provider durch `provider`-Filter beziehungsweise `max_price`. `issues` nennt die Ursache je Provider (`no_endpoint`).

## Antwort 408: application/json

Der Provider hat innerhalb der Frist keine Verbindung aufgebaut oder seine Antwort nicht abgeschlossen, oder der Anfrageinhalt traf nicht weiter ein (`timeout`).

## Antwort 409: application/json

idempotency_conflict: Der Key gehört zu anderem Anfrageinhalt; einen neuen Key verwenden. idempotency_in_progress: Der ursprüngliche Vorgang läuft noch; Retry-After beachten. idempotency_unavailable: Eine sichere Wiederholung ist nicht möglich; nicht still neu berechnen lassen. remedy_hint beachten.

## Antwort 413: application/json

Der Anfrageinhalt oder das dekodierte Audio überschreitet 50 MiB (`payload_too_large`).

## Antwort 429: application/json

Kundenkontingent oder Anfragelimit des Upstreams erschöpft (`rate_limited`)

## Antwort 500: application/json

Unerwarteter Gateway-Fehler (`internal`)

## Antwort 501: application/json

feature_unavailable: A required feature is permanently unconfigured on this gateway, for example encrypted idempotency replay without its encryption key, PII redaction without a detector, or BYOK import without import keys. Ask the operator to configure it or remove the optional feature from the request. Retrying the identical request cannot enable the feature: retryable is false and no Retry-After header is sent. Temporary cache, database, detector or provider outages, pending imports and missing or revoked individual customer credentials retain their existing error types.

## Antwort 502: application/json

Der einzige versuchte Provider ist fehlgeschlagen (`provider_error` mit `provider_name` und strukturierten `provider_error`-Diagnosen, ohne Provider-Text) oder hat eine Antwort ohne `text`, über 32 MiB groß oder zu komplex zu parsen gesendet (`provider_invalid_response`).

## Antwort 503: application/json

Alle Provider fehlgeschlagen, Gateway durch andere große Anfrageinhalte ausgelastet oder diese Gateway-Instanz wird beendet (`no_provider_available`).
