Référence des erreurs

Toutes les réponses d'erreur ont la même structure. Code de statut + code lisible par une machine + message pour un humain + field facultatif qui désigne l'entrée en cause.

Enveloppe

{
  "success": false,
  "error": "Content length (5000) exceeds maximum allowed (4296 characters).",
  "code": "CONTENT_TOO_LONG",
  "field": "content"
}

Codes de statut HTTP

Statut	Signification
`200`	Succès
`400`	Erreur de validation : corrigez l'entrée et réessayez
`401`	En-tête d'authentification absent ou incorrect
`402`	Passerelle des clés utilisateur : formule Studio manquante ou crédits API épuisés
`404`	Endpoint introuvable
`413`	Corps trop volumineux (>10 MB) ou, via la passerelle des clés utilisateur, un fichier généré de plus de 10 MB (`output_too_large`)
`422`	Le moteur n'a pas pu produire un QR scannable, même après correction automatique (`QR_UNSCANNABLE`), ou la sortie dépasserait le budget (`OUTPUT_TOO_COMPLEX`)
`429`	Limite de débit : voir `Retry-After`
`500`	Erreur interne : journalisez et réessayez
`503`	Serveur occupé (nombreux rendus simultanés) ou fournisseurs IA à court de capacité (`AI_QUOTA_EXCEEDED`)

Erreurs de validation (400)

Code	Signification
`MISSING_REQUIRED_FIELD`	`content` (ou `prompt` sur les endpoints IA) est vide
`CONTENT_TOO_LONG`	Contenu encodé > 4296 caractères (maximum théorique d'un QR)
`INVALID_JSON`	Le corps n'est pas un JSON valide
`INVALID_HEX`	Une couleur n'est pas au format `#RGB`, `#RRGGBB` ou `#RRGGBBAA`
`INVALID_FIELD_VALUE`	Générique : `field` vous indique lequel
`VALUE_OUT_OF_RANGE`	Champ numérique hors des bornes documentées
`LOW_CONTRAST`	premier plan vs arrière-plan < 4:1 ; le moteur ne peut pas corriger automatiquement
`LOGO_TOO_LARGE`	`logoSizePercent` > 25 avec un ECC < H
`FILE_TOO_LARGE`	Envoi multipart > 10 MB
`MULTIPART_CONFIG_MISSING`	Champ `config` absent de la requête form-data

Erreurs d'authentification (401)

Code	Signification
`UNAUTHORIZED`	`X-RapidAPI-Proxy-Secret` absent ou incorrect
`INVALID_INTERNAL_SIGNATURE`	Échec de la vérification HMAC du BFF
`INTERNAL_TS_EXPIRED`	Horodatage du BFF hors de la fenêtre de ±60 s
`LLM_API_KEY_INVALID`	Votre clé de fournisseur (uniquement sur l'endpoint IA de la marketplace)

Erreurs de la passerelle des clés utilisateur

La passerelle https://qr-branding.com/api/v1/* (Clés API utilisateur) ajoute ses propres codes, en minuscules, avec la même enveloppe success / error / code :

Statut	Code	Signification
`400`	`invalid_body`	Le corps n'a pas pu être interprété
`401`	`missing_api_key`	L'en-tête `X-API-Key` est absent
`401`	`invalid_api_key`	Clé non reconnue, révoquée ou mal formée
`402`	`studio_required`	La clé est valide, mais le compte n'a pas de pack Studio actif. Inclut les liens `docs` et `pricing`
`402`	`out_of_api_credits`	Génération IA sur nos clés sans crédits Studio restants. Inclut les liens `docs` et `pricing`
`413`	`payload_too_large`	Corps de plus de 1 Mio
`413`	`output_too_large`	Le fichier généré dépasse 10 MB. Demandez du PNG ou un `outputWidth` plus petit
`415`	`multipart_not_supported`	La passerelle n'accepte que du JSON

Erreurs du paiement

POST /api/checkout (le bouton d'achat de /pricing) répond { "error": "withdrawal_waiver_required" } quand l'accord manque :

Statut	Code	Signification
`400`	`withdrawal_waiver_required`	La case précédant le paiement (accord et renonciation au droit de rétractation) n'a pas été cochée. Voir Tarifs et crédits

Erreurs de génération IA

Code	Signification
`AI_GENERATION_FAILED`	Le LLM n'a renvoyé aucune configuration exploitable : essayez un prompt plus clair
`AI_REQUEST_TIMEOUT`	Aucun fournisseur de la chaîne de repli n'a répondu dans le délai total de 45 s (20 s au plus chacun). Répond 503 ; réessayez dans un instant
`AI_QUOTA_EXCEEDED`	Tous les fournisseurs de la chaîne de repli ont refusé pour quota ou plafond de dépenses. Répond 503 ; réessayer tout de suite ne sert à rien, réessayez plus tard
`AI_CONFIG_INVALID`	Le LLM a renvoyé une configuration rejetée par le moteur (rare ; réessayez avec une créativité plus basse)
`INVALID_LLM_PROVIDER`	Marketplace uniquement : `llmProvider` ne fait pas partie de `openai anthropic google mistral cohere groq xai deepseek qwen local`
`INVALID_LLM_MODEL`	Marketplace uniquement : `llmModel` n'a pas le format d'un identifiant de modèle

Erreurs de budget de sortie (422)

Code	Signification
`OUTPUT_TOO_COMPLEX`	Le design produirait un SVG ou un PDF de plus de 20 MB, ou un canevas raster interne de plus de 5120 px de côté. La taille d’un SVG croît avec le nombre de modules : un modèle avec une URL courte pèse ~1,5 MB, avec une URL de 300 caractères ~17 MB. Exportez en PNG, raccourcissez le contenu ou utilisez des formes de modules plus simples

Erreurs serveur (500/503)

Code	Signification
`INTERNAL_ERROR`	Inattendu : signalez-le avec l'identifiant de la requête
`QR_GENERATION_FAILED`	Le moteur de rendu lui-même a levé une exception. Inclut le champ en cause lorsqu'il est connu
`SERVER_BUSY`	Trop de rendus haute résolution simultanés. Patientez et réessayez

Contraintes de validation des champs

Champ	Contrainte
`content`	1–4296 caractères
`prompt` (IA)	1–10000 caractères
`creativity` (IA)	`0.0–1.0`
`pixelsPerModule`	`1–100`
`outputWidth` / `outputHeight`	`64–4096`
`logoSizePercent`	`3–40` (le moteur plafonne en douceur à `25` avec l'ECC H)
`moduleScale`	`0.5–1.0`
`moduleSizeVariation`	`0.0–0.15` (plafond souple ; au-delà, le scan ne fonctionne plus)
`qrShapeRadius`	`0–50`
Taille du fichier de logo / de fond	≤ 10 MB
Types d'image de logo / de fond	PNG, JPG, GIF, BMP, WebP
Document SVG / PDF	≤ 20 MB (`OUTPUT_TOO_COMPLEX`)
Fichier via la passerelle des clés utilisateur	≤ 10 MB (`output_too_large`)