# Embeddings erstellen

Turns texts (or token IDs, or multimodal inputs for models that accept media) into
embedding vectors, one per input in the order of `input`. Same format as OpenRouter and
OpenAI; `usage.cost` is the EUR cost of the successful result attempt across its batches.
Confirmed paid costs of earlier failed attempts remain charged and are additionally
included in generation lookup and the durable billing receipt.

The gateway picks a European provider of the model (respecting `provider` preferences) and,
if it fails, tries the next one. The body is validated completely before any provider is
called; every problem is listed in `error.metadata.issues`. Unknown parameters are ignored
and named in `x-ignored-params`. Responses are bounded like chat responses (32 MiB, see
"Limits"): large batches of long vectors fit better with `encoding_format: base64`.

Administrative PII requirements are checked for each actual route, including fallbacks
and retries. This endpoint cannot redact its input: a matching requirement returns
`invalid_parameter` with a `not_available` issue at `$.model` before provider I/O.

`POST https://api.tokenlane.de/v1/embeddings`

## 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/embeddings' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "encoding_format": "float",
  "input": [
    "Lisbon is the capital of Portugal.",
    "Porto lies on the Douro."
  ],
  "model": "baai/bge-m3"
}'
```

## node

```node
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.embeddings.create({
  "encoding_format": "float",
  "input": [
    "Lisbon is the capital of Portugal.",
    "Porto lies on the Douro."
  ],
  "model": "baai/bge-m3"
}, {});
console.log(response);
```

## python

```python
import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "encoding_format": "float",
  "input": [
    "Lisbon is the capital of Portugal.",
    "Porto lies on the Douro."
  ],
  "model": "baai/bge-m3"
}''')
response = client.embeddings.create(
    model=body["model"],
    input=body["input"],
    encoding_format=body["encoding_format"]
)
print(response)
```

## vercel

```vercel
// This operation uses HTTP directly.
const response = await fetch("https://api.tokenlane.de/v1/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Content-Type": "application/json",
  },
  body: `{
  "encoding_format": "float",
  "input": [
    "Lisbon is the capital of Portugal.",
    "Porto lies on the Douro."
  ],
  "model": "baai/bge-m3"
}`,
});
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 the body 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
{
  "encoding_format": "float",
  "input": [
    "Lisbon is the capital of Portugal.",
    "Porto lies on the Douro."
  ],
  "model": "baai/bge-m3"
}
```

### s14: object

Texte, Token-IDs oder multimodale Eingaben zur Umwandlung in Embedding-Vektoren im OpenRouter-Format. OpenAI- und OpenRouter-Clients können durch Ändern von Base-URL und API-Key weiterverwendet werden.

Vor jedem Provider-Aufruf wird der Anfrageinhalt validiert. Alle Probleme stehen in `error.metadata.issues`. Grenzen: höchstens 2048 Eingaben, jede innerhalb der Modell-Kontextlänge. Geschätzt wird mit vier Textbytes je Token; eine Überschreitung führt zu 400 `context_length_exceeded`. Es gelten der 50-MiB-Anfrageinhalt und seine Strukturgrenze, siehe „Grenzen“ in der Einführung. Unbekannte Parameter werden ignoriert und in `x-ignored-params` genannt.

{}

```json
{
  "encoding_format": "float",
  "input": [
    "Lisbon is the capital of Portugal.",
    "Porto lies on the Douro."
  ],
  "model": "mistralai/mistral-embed"
}
```

- dimensions (optional): s291

### s291: integer

Vektorlänge für Modelle, die verkürzte Vektoren unterstützen.

{"minimum":"1"}

```json
1024
```

- encoding_format (optional): s292

### s292: string

`float` ist der Standard und liefert Zahlenarrays. `base64` liefert Little-Endian-32-Bit-Gleitkommazahlen als Base64-Zeichenketten mit ungefähr einem Viertel der Größe. Für große Mengen geeignet.

"float", "base64"

{}

```json
"float"
```

- input (Pflichtfeld): s293

### s293: anyOf

Text-, Token- oder multimodale Eingaben zur Erzeugung von Embeddings

{}

```json
"Lisbon is the capital of Portugal."
```

anyOf: s1057

### s1057: string

{"minLength":"1"}

anyOf: s1058

### s1058: array

{}

anyOf: s1059

### s1059: array

{}

### s1251: number

{}

anyOf: s1060

### s1060: array

{}

### s1252: array

{}

anyOf: s1061

### s1061: array

{}

### s1253: object

Eine multimodale Eingabe für Modelle, die ihre Medien akzeptieren (`architecture.input_modalities` unter `GET /v1/models`).

{}

```json
{
  "content": [
    {
      "text": "A cat",
      "type": "text"
    },
    {
      "image_url": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
      },
      "type": "image_url"
    }
  ]
}
```

- content (Pflichtfeld): s1335

### s1335: array

{"minItems":"1"}

### s1349: oneOf

{}

oneOf: s1351

### s1351: object

{}

- text (Pflichtfeld): s1057

- type (Pflichtfeld): s1089

### s1089: string

"text"

{}

oneOf: s1352

### s1352: object

{}

- image_url (Pflichtfeld): s1353

### s1353: object

{}

- url (Pflichtfeld): s7

### s7: string

{}

- type (Pflichtfeld): s1229

### s1229: string

"image_url"

{}

oneOf: s94

### s94: object

Audio einer multimodalen Embedding-Eingabe.

{}

```json
{
  "input_audio": {
    "data": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAA=",
    "format": "wav"
  },
  "type": "input_audio"
}
```

- input_audio (Pflichtfeld): s566

### s566: object

Audio einer multimodalen Embedding-Eingabe.

{}

```json
{
  "data": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAA=",
  "format": "wav"
}
```

- data (Pflichtfeld): s907

### s907: string

Medien als Base64-Daten-URL (`data:<media type>;base64,<data>`) oder als reines Base64.

{}

- format (optional): s908

### s908: string

Medienformat, beispielsweise `wav`, `mp4` oder `pdf`.

{}

```json
"wav"
```

- type (Pflichtfeld): s567

### s567: string

Typ des Teils. Benennt das Feld mit den Medien.

"input_audio"

{}

```json
"input_audio"
```

oneOf: s96

### s96: object

Ein Video einer multimodalen Embedding-Eingabe.

{}

```json
{
  "input_video": {
    "data": "data:video/mp4;base64,AAAAGGZ0eXBtcDQyAAAAAGlzb20=",
    "format": "mp4"
  },
  "type": "input_video"
}
```

- input_video (Pflichtfeld): s570

### s570: object

Ein Video einer multimodalen Embedding-Eingabe.

{}

```json
{
  "data": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAA=",
  "format": "wav"
}
```

- data (Pflichtfeld): s907

Medien als Base64-Daten-URL (`data:<media type>;base64,<data>`) oder als reines Base64.

- format (optional): s908

Medienformat, beispielsweise `wav`, `mp4` oder `pdf`.

- type (Pflichtfeld): s571

### s571: string

Typ des Teils. Benennt das Feld mit den Medien.

"input_video"

{}

```json
"input_video"
```

oneOf: s95

### s95: object

Ein Dokument einer multimodalen Embedding-Eingabe.

{}

```json
{
  "input_file": {
    "data": "data:application/pdf;base64,JVBERi0xLjQK",
    "format": "pdf"
  },
  "type": "input_file"
}
```

- input_file (Pflichtfeld): s568

### s568: object

Ein Dokument einer multimodalen Embedding-Eingabe.

{}

```json
{
  "data": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAA=",
  "format": "wav"
}
```

- data (Pflichtfeld): s907

Medien als Base64-Daten-URL (`data:<media type>;base64,<data>`) oder als reines Base64.

- format (optional): s908

Medienformat, beispielsweise `wav`, `mp4` oder `pdf`.

- type (Pflichtfeld): s569

### s569: string

Typ des Teils. Benennt das Feld mit den Medien.

"input_file"

{}

```json
"input_file"
```

- input_type (optional): s294

### s294: string

Verwendungszweck der Eingabe für Modelle, die Suchanfragen und Dokumente unterschiedlich einbetten, beispielsweise `search_query` oder `search_document`. Wird unverändert an den Provider gesendet.

{}

```json
"search_document"
```

- metadata (optional): s295

### s295: any

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

{}

- model (Pflichtfeld): s296

### s296: string

Embedding-Modell mit derselben ID wie bei OpenRouter oder einem Gateway-Alias. Chatmodelle können keine Embeddings erzeugen. Ihre ID scheitert mit 404 `no_endpoint`. Eine unbekannte ID scheitert mit 400 `model_not_found` und einem Vorschlag unter `remedy_hint`.

{}

```json
"mistralai/mistral-embed"
```

- provider (optional): s297

### s297: object

Routing-Einstellungen wie bei Chat Completions: `only`, `ignore`, `order`, `allow_fallbacks`, `require_parameters`, `sort` und `max_price` (EUR pro Million Tokens). Scheitert ein Provider, wird der nächste versucht.

{}

- 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"
```

- trace (optional): s252

### s252: object

Ablaufmetadaten zur Beobachtbarkeit. Werden nie an den Provider gesendet.

{}

- user (optional): s298

### s298: string

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

{}

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

## Antwort 200: application/json

Ein Vektor je Eingabe mit Tokenzahlen und EUR-Kosten unter `usage`. Immer JSON: Embeddings werden nie gestreamt. `text/event-stream` ist nur zur Kompatibilität mit der OpenRouter-Beschreibung aufgeführt.

```json
{
  "data": [
    {
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347
      ],
      "index": 0,
      "object": "embedding"
    }
  ],
  "id": "gen-01k7tm9qz3f5c8x2v6b4n0m7hd",
  "model": "mistralai/mistral-embed",
  "object": "list",
  "provider": "mistral",
  "usage": {
    "cost": 8e-7,
    "cost_details": {
      "currency": "EUR",
      "upstream_inference_completions_cost": 0,
      "upstream_inference_cost": 8e-7,
      "upstream_inference_prompt_cost": 8e-7
    },
    "currency": "EUR",
    "is_byok": false,
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

### s15: object

Embedding-Vektoren im OpenRouter-Format mit EUR-Kosten.

{}

```json
{
  "data": [
    {
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347
      ],
      "index": 0,
      "object": "embedding"
    }
  ],
  "id": "gen-01k7tm9qz3f5c8x2v6b4n0m7hd",
  "model": "mistralai/mistral-embed",
  "object": "list",
  "provider": "mistral",
  "usage": {
    "cost": 8e-7,
    "cost_details": {
      "currency": "EUR",
      "upstream_inference_completions_cost": 0,
      "upstream_inference_cost": 8e-7,
      "upstream_inference_prompt_cost": 8e-7
    },
    "currency": "EUR",
    "is_byok": false,
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}
```

- data (Pflichtfeld): s299

### s299: array

Ein Vektor je Eingabe in der Reihenfolge der Eingaben (`index`).

{}

### s117: object

Vektor einer Eingabe.

{}

```json
{
  "embedding": [
    0.0023064255,
    -0.009327292,
    0.015797347
  ],
  "index": 0,
  "object": "embedding"
}
```

- embedding (Pflichtfeld): s624

### s624: anyOf

Vektor als Zahlen oder bei `encoding_format: base64` als Base64-Zeichenkette

{}

```json
[
  0.0023064255,
  -0.009327292,
  0.015797347
]
```

anyOf: s1157

### s1157: array

{}

anyOf: s7

- index (Pflichtfeld): s625

### s625: integer

Position der Eingabe unter `input`.

int32

{"minimum":"0"}

```json
0
```

- object (Pflichtfeld): s626

### s626: string

Immer `embedding`.

"embedding"

{}

```json
"embedding"
```

- id (Pflichtfeld): s300

### s300: string

ID dieser Generierung. `GET /v1/generation?id=` zeigt Tokens, Kosten und Laufzeiten.

{}

```json
"gen-01k7tm9qz3f5c8x2v6b4n0m7hd"
```

- model (Pflichtfeld): s301

### s301: string

Modell, das die Embeddings erzeugt hat, als öffentliche Modell-ID.

{}

```json
"mistralai/mistral-embed"
```

- object (Pflichtfeld): s302

### s302: string

Immer `list`.

"list"

{}

```json
"list"
```

- usage (optional): s303

### s303: object

Token counts and EUR cost of the successful result attempt, including all its batches,
if the provider reported input tokens. Earlier paid attempts that failed before a
successful fallback remain charged and are included in `GET /v1/generation` and the
durable billing receipt, not this result's usage. Without confirmed input tokens,
`cost` is missing rather than zero.

{}

```json
{
  "cost": 8e-7,
  "currency": "EUR",
  "is_byok": false,
  "prompt_tokens": 8,
  "total_tokens": 8
}
```

- cost (optional): s627

### s627: number

EUR cost of the successful result attempt across all its batches. Generation lookup
and the durable receipt additionally include confirmed costs of earlier failed attempts.

double

{}

```json
8e-7
```

- currency (optional): s628

### s628: string

Immer `EUR`.

{}

```json
"EUR"
```

- is_byok (optional): s629

### s629: boolean

Ob ein eigener Provider-Key des Clients verwendet wurde. Immer false, da das Gateway kein BYOK anbietet.

{}

- prompt_tokens (Pflichtfeld): s630

### s630: integer

Eingabetokens nach Zählung des Providers.

int64

{"minimum":"0"}

```json
8
```

- total_tokens (Pflichtfeld): s631

### s631: integer

Alle Tokens. Identisch mit `prompt_tokens`.

int64

{"minimum":"0"}

```json
8
```

- * (optional): s632

### s632: any

Öffentliche `cost_details` schlüsseln Eingabe- und Ausgabekosten in EUR auf, gegebenenfalls mit ursprünglicher Währung und Wechselkursdetails. Unbekannte Provider-Nutzungsfelder werden entfernt.

{}

- * (optional): s304

### s304: any

Öffentliche Erweiterung `provider`. Unbekannte Felder der Provider-Antwortstruktur werden entfernt.

{}

## Antwort 200: text/event-stream

Ein Vektor je Eingabe mit Tokenzahlen und EUR-Kosten unter `usage`. Immer JSON: Embeddings werden nie gestreamt. `text/event-stream` ist nur zur Kompatibilität mit der OpenRouter-Beschreibung aufgeführt.

```text
YOUR_VALUE
```

## 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 (`invalid_request`), ungültige Felder wie leeres oder fehlendes `input` oder mehr als 2048 Eingaben mit allen Problemen unter `issues` (`invalid_parameter`), eine unbekannte Modell-ID mit Vorschlag unter `remedy_hint` (`model_not_found`) oder eine für das Modell zu lange Eingabe (`context_length_exceeded`).

```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: kein Embedding-Modell oder Ausschluss aller Provider durch `provider`-Filter, `max_price` oder Medien. `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 überschreitet 50 MiB oder seine geparste JSON-Struktur ohne JSON-Zeichenkettenwerte würde mehr als 20 MiB benötigen (`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 gesendet, die keine Embedding-Liste, über 32 MiB groß oder zu komplex zu parsen ist (`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`).
