Jede Fehlerantwort hat dieselbe Struktur. Statuscode + maschinenlesbarer code + Meldung für Menschen + optional field, das auf die fehlerhafte Eingabe zeigt.
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
| Status | Bedeutung |
|---|
200 | Erfolg |
400 | Validierungsfehler – Eingabe korrigieren und erneut versuchen |
401 | Auth-Header fehlt oder ist falsch |
402 | Gateway für Nutzerschlüssel: Studio-Plan fehlt oder API-Credits aufgebraucht |
404 | Endpunkt nicht gefunden |
413 | Body zu groß (>10 MB) oder, über das Gateway für Nutzerschlüssel, eine erzeugte Datei über 10 MB (output_too_large) |
422 | Die Engine konnte selbst nach automatischer Korrektur keinen scanbaren QR-Code erzeugen (QR_UNSCANNABLE), oder die Ausgabe würde das Budget sprengen (OUTPUT_TOO_COMPLEX) |
429 | Rate-Limit – siehe Retry-After |
500 | Intern – protokollieren + erneut versuchen |
503 | Server ausgelastet (viele gleichzeitige große Renderings) oder KI-Anbieter ohne Kapazität (AI_QUOTA_EXCEEDED) |
| Code | Bedeutung |
|---|
MISSING_REQUIRED_FIELD | content (bzw. prompt bei KI-Endpunkten) ist leer |
CONTENT_TOO_LONG | Codierter Payload > 4296 Zeichen (theoretisches QR-Maximum) |
INVALID_JSON | Body lässt sich nicht als JSON parsen |
INVALID_HEX | Ein Farbwert ist nicht #RGB, #RRGGBB oder #RRGGBBAA |
INVALID_FIELD_VALUE | Allgemein – field sagt dir, welches |
VALUE_OUT_OF_RANGE | Numerisches Feld außerhalb der dokumentierten Grenzen |
LOW_CONTRAST | Vordergrund vs. Hintergrund < 4:1; die Engine kann es nicht automatisch korrigieren |
LOGO_TOO_LARGE | logoSizePercent > 25 bei ECC < H |
FILE_TOO_LARGE | Multipart-Upload > 10 MB |
MULTIPART_CONFIG_MISSING | Feld config fehlt in der form-data-Anfrage |
| Code | Bedeutung |
|---|
UNAUTHORIZED | X-RapidAPI-Proxy-Secret fehlt oder ist falsch |
INVALID_INTERNAL_SIGNATURE | BFF-HMAC-Prüfung fehlgeschlagen |
INTERNAL_TS_EXPIRED | BFF-Zeitstempel außerhalb des ±60-s-Fensters |
LLM_API_KEY_INVALID | Dein Anbieter-Schlüssel (nur beim Marketplace-KI-Endpunkt) |
Das Gateway https://qr-branding.com/api/v1/* (Eigene API-Schlüssel) ergänzt eigene Codes in Kleinbuchstaben, mit demselben Format success / error / code:
| Status | Code | Bedeutung |
|---|
400 | invalid_body | Der Body ließ sich nicht auswerten |
401 | missing_api_key | Der Header X-API-Key fehlt |
401 | invalid_api_key | Schlüssel unbekannt, widerrufen oder fehlerhaft |
402 | studio_required | Gültiger Schlüssel, aber das Konto hat kein aktives Studio-Paket. Enthält die Links docs und pricing |
402 | out_of_api_credits | KI-Generierung mit unseren Schlüsseln ohne verbleibende Studio-Credits. Enthält die Links docs und pricing |
413 | payload_too_large | Body größer als 1 MiB |
413 | output_too_large | Die erzeugte Datei ist größer als 10 MB. PNG oder eine kleinere outputWidth anfordern |
415 | multipart_not_supported | Das Gateway akzeptiert nur JSON |
POST /api/checkout (der Kaufen-Button auf /pricing) antwortet mit { "error": "withdrawal_waiver_required" }, wenn die Zustimmung fehlt:
| Status | Code | Bedeutung |
|---|
400 | withdrawal_waiver_required | Das Kontrollkästchen vor der Zahlung (Zustimmung und Verzicht auf das Widerrufsrecht) wurde nicht angehakt. Siehe Preise & Credits |
| Code | Bedeutung |
|---|
AI_GENERATION_FAILED | Das LLM hat keine brauchbare Konfiguration geliefert – versuch einen klareren Prompt |
AI_REQUEST_TIMEOUT | Kein Anbieter der Fallback-Kette hat innerhalb der Gesamtfrist von 45 s geantwortet (jeder hat höchstens 20 s). Antwort 503; gleich erneut versuchen |
AI_QUOTA_EXCEEDED | Alle Anbieter der Fallback-Kette haben wegen Kontingent oder Ausgabenlimit abgelehnt. Antwort 503; ein sofortiger neuer Versuch hilft nicht, später erneut versuchen |
AI_CONFIG_INVALID | Das LLM hat eine Konfiguration geliefert, die die Engine abgelehnt hat (selten, mit niedrigerer Kreativität erneut versuchen) |
INVALID_LLM_PROVIDER | Nur Marketplace – llmProvider ist nicht in openai anthropic google mistral cohere groq xai deepseek qwen local |
INVALID_LLM_MODEL | Nur Marketplace – llmModel ist keine gültige Modell-ID |
| Code | Bedeutung |
|---|
OUTPUT_TOO_COMPLEX | Das Design würde ein SVG oder PDF über 20 MB oder eine interne Raster-Leinwand über 5120 px pro Seite erzeugen. Die Größe eines SVG wächst mit der Zahl der Module: eine Vorlage mit kurzer URL hat ~1,5 MB, mit einer URL von 300 Zeichen ~17 MB. Als PNG exportieren, den Inhalt kürzen oder einfachere Modulformen verwenden |
| Code | Bedeutung |
|---|
INTERNAL_ERROR | Unerwartet – bitte mit der Request-ID melden |
QR_GENERATION_FAILED | Die Render-Engine selbst hat einen Fehler geworfen. Enthält das betroffene Feld, sofern bekannt |
SERVER_BUSY | Zu viele gleichzeitige hochauflösende Renderings. Warten und erneut versuchen |
| Feld | Vorgabe |
|---|
content | 1–4296 Zeichen |
prompt (KI) | 1–10000 Zeichen |
creativity (KI) | 0.0–1.0 |
pixelsPerModule | 1–100 |
outputWidth / outputHeight | 64–4096 |
logoSizePercent | 3–40 (die Engine begrenzt bei ECC H weich auf 25) |
moduleScale | 0.5–1.0 |
moduleSizeVariation | 0.0–0.15 (weiche Grenze, alles darüber macht das Scannen kaputt) |
qrShapeRadius | 0–50 |
| Dateigröße Logo / Hintergrund | ≤ 10 MB |
| Bildtypen Logo / Hintergrund | PNG, JPG, GIF, BMP, WebP |
| SVG- / PDF-Dokument | ≤ 20 MB (OUTPUT_TOO_COMPLEX) |
| Datei über das Gateway für Nutzerschlüssel | ≤ 10 MB (output_too_large) |