Error Codes

Fehlerformat

Alle API-Fehler verwenden ein einheitliches JSON-Format:

{
  "detail": {
    "error": {
      "code": "ERROR_CODE",
      "message": "Menschenlesbare Beschreibung."
    }
  }
}

HTTP	Code	Beschreibung	Retry
401	`UNAUTHORIZED`	Kein oder ungueltiger API Key im `Authorization`-Header.	Nein — Key pruefen.

HTTP	Code	Beschreibung	Retry
429	`RATE_LIMIT_EXCEEDED`	Zu viele Requests.	Ja — nach `Retry-After` Sekunden.

Der Retry-After-Header gibt die Wartezeit in Sekunden an.

HTTP	Code	Beschreibung	Retry
402	`INSUFFICIENT_ENRICHMENTS`	Nicht genug Enrichments.	Nein — Enrichments kaufen.

HTTP	Code	Beschreibung	Retry
422	`VALIDATION_ERROR`	Ungueltige Produktdaten (z.B. `product_name` fehlt oder leer).	Nein — Request korrigieren.
422	(Pydantic)	Felder mit falschem Typ oder ausserhalb der Grenzen.	Nein — Request korrigieren.

HTTP	Code	Beschreibung	Retry
502	`LLM_UNAVAILABLE`	KI-Provider voruebergehend nicht erreichbar.	Ja — nach wenigen Sekunden.
502	`LLM_ERROR`	KI-Provider hat einen Fehler zurueckgegeben.	Ja — nach wenigen Sekunden.
503	`LLM_RATE_LIMIT`	KI-Provider Rate Limit erreicht.	Ja — nach `Retry-After` Sekunden (Standard: 10s).

HTTP	Code	Beschreibung	Retry
401	—	Ungueltige HMAC-Signatur.	Nein — Webhook-Secret pruefen.
400	—	Ungueltiger JSON-Body oder Payload-Struktur.	Nein — Payload pruefen.

HTTP	Code	Beschreibung	Retry
400	`INVALID_REQUEST`	Account konnte nicht erstellt werden (z.B. doppelte E-Mail).	Nein — andere E-Mail verwenden oder weglassen.
429	`RATE_LIMIT_EXCEEDED`	Mehr als 5 Key-Erstellungen pro Stunde pro IP.	Ja — nach `Retry-After` Sekunden.

Retry bei 502/503 — LLM-Provider-Fehler sind voruebergehend. Exponential Backoff empfohlen.
Kein Retry bei 401/402/422 — Diese Fehler erfordern eine Aenderung am Request.
X-Request-ID loggen — Bei Support-Anfragen die Request-ID mitgeben.
Retry-After beachten — Bei 429 und 503 immer den Header-Wert verwenden.