Ogni risposta di errore ha la stessa struttura: codice di stato + code leggibile dalle macchine + messaggio per le persone + field facoltativo che indica l'input responsabile.
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
| Stato | Significato |
|---|
200 | Successo |
400 | Errore di convalida: correggi l'input e riprova |
401 | Header di autenticazione mancante o errato |
402 | Gateway delle chiavi utente: manca il piano Studio o i crediti API sono esauriti |
404 | Endpoint non trovato |
413 | Corpo troppo grande (>10 MB) oppure, tramite il gateway delle chiavi utente, un file generato oltre i 10 MB (output_too_large) |
422 | Il motore non è riuscito a produrre un QR scansionabile nemmeno dopo la correzione automatica (QR_UNSCANNABLE), oppure l’output supererebbe il budget (OUTPUT_TOO_COMPLEX) |
429 | Limite di richieste: vedi Retry-After |
500 | Errore interno: registralo nei log e riprova |
503 | Server occupato (molte generazioni pesanti in parallelo) oppure provider IA senza capacità (AI_QUOTA_EXCEEDED) |
| Codice | Significato |
|---|
MISSING_REQUIRED_FIELD | content (o prompt sugli endpoint IA) è vuoto |
CONTENT_TOO_LONG | Contenuto codificato > 4296 caratteri (massimo teorico di un QR) |
INVALID_JSON | Il corpo non è un JSON valido |
INVALID_HEX | Una stringa di colore non è #RGB, #RRGGBB o #RRGGBBAA |
INVALID_FIELD_VALUE | Generico: field ti dice quale |
VALUE_OUT_OF_RANGE | Campo numerico fuori dai limiti documentati |
LOW_CONTRAST | primo piano vs sfondo < 4:1; il motore non riesce a correggerlo in automatico |
LOGO_TOO_LARGE | logoSizePercent > 25 con ECC < H |
FILE_TOO_LARGE | Caricamento multipart > 10 MB |
MULTIPART_CONFIG_MISSING | Campo config assente nella richiesta form-data |
| Codice | Significato |
|---|
UNAUTHORIZED | X-RapidAPI-Proxy-Secret mancante o errato |
INVALID_INTERNAL_SIGNATURE | Verifica HMAC del BFF non riuscita |
INTERNAL_TS_EXPIRED | Timestamp del BFF fuori dalla finestra di ±60s |
LLM_API_KEY_INVALID | La chiave del tuo provider (solo sull'endpoint IA del marketplace) |
Il gateway https://qr-branding.com/api/v1/* (Chiavi API utente) aggiunge i propri codici, in minuscolo, con la stessa struttura success / error / code:
| Stato | Codice | Significato |
|---|
400 | invalid_body | Impossibile interpretare il corpo |
401 | missing_api_key | Manca l'intestazione X-API-Key |
401 | invalid_api_key | Chiave non riconosciuta, revocata o malformata |
402 | studio_required | La chiave è valida, ma l'account non ha un pacchetto Studio attivo. Include i link docs e pricing |
402 | out_of_api_credits | Generazione IA sulle nostre chiavi senza crediti Studio residui. Include i link docs e pricing |
413 | payload_too_large | Corpo oltre 1 MiB |
413 | output_too_large | Il file generato supera i 10 MB. Richiedi PNG o un outputWidth più piccolo |
415 | multipart_not_supported | Il gateway accetta solo JSON |
POST /api/checkout (il pulsante di acquisto di /pricing) risponde { "error": "withdrawal_waiver_required" } quando manca il consenso:
| Stato | Codice | Significato |
|---|
400 | withdrawal_waiver_required | La casella prima del pagamento (consenso e rinuncia al diritto di recesso) non è stata selezionata. Vedi Prezzi e crediti |
| Codice | Significato |
|---|
AI_GENERATION_FAILED | L'LLM non ha restituito una configurazione utilizzabile: prova con un prompt più chiaro |
AI_REQUEST_TIMEOUT | Nessun provider della catena di fallback ha risposto entro il limite totale di 45 s (al massimo 20 s ciascuno). Risponde 503; riprova tra un momento |
AI_QUOTA_EXCEEDED | Tutti i provider della catena di fallback hanno rifiutato per quota o tetto di spesa. Risponde 503; riprovare subito non serve, riprova più tardi |
AI_CONFIG_INVALID | L'LLM ha restituito una configurazione rifiutata dal motore (raro, riprova con una creatività più bassa) |
INVALID_LLM_PROVIDER | Solo marketplace: llmProvider non è tra openai anthropic google mistral cohere groq xai deepseek qwen local |
INVALID_LLM_MODEL | Solo marketplace: llmModel non ha il formato di un ID di modello |
| Codice | Significato |
|---|
OUTPUT_TOO_COMPLEX | Il design produrrebbe un SVG o un PDF oltre i 20 MB, oppure una tela raster interna oltre i 5120 px per lato. La dimensione di un SVG cresce con il numero di moduli: un modello con un URL breve pesa ~1,5 MB, con un URL di 300 caratteri ~17 MB. Esporta in PNG, accorcia il contenuto o usa forme di modulo più semplici |
| Codice | Significato |
|---|
INTERNAL_ERROR | Imprevisto: segnalalo indicando l'id della richiesta |
QR_GENERATION_FAILED | Ha generato un errore il motore di rendering stesso. Include il campo responsabile quando è noto |
SERVER_BUSY | Troppe generazioni ad alta risoluzione in parallelo. Attendi e riprova |
| Campo | Vincolo |
|---|
content | 1–4296 caratteri |
prompt (IA) | 1–10000 caratteri |
creativity (IA) | 0.0–1.0 |
pixelsPerModule | 1–100 |
outputWidth / outputHeight | 64–4096 |
logoSizePercent | 3–40 (il motore applica un limite morbido di 25 con ECC H) |
moduleScale | 0.5–1.0 |
moduleSizeVariation | 0.0–0.15 (limite morbido: valori più alti compromettono la scansione) |
qrShapeRadius | 0–50 |
| Dimensione del file di logo / sfondo | ≤ 10 MB |
| Tipi di immagine per logo / sfondo | PNG, JPG, GIF, BMP, WebP |
| Documento SVG / PDF | ≤ 20 MB (OUTPUT_TOO_COMPLEX) |
| File tramite il gateway delle chiavi utente | ≤ 10 MB (output_too_large) |