Codici di errore e diagnostica

Struttura standard degli errori HTTP, tabella dei codici e buone pratiche.

Quando una richiesta non può essere elaborata con successo, SmallPict restituisce un codice di stato HTTP standard con un payload JSON dettagliato.

Struttura JSON degli errori

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "Il file fornito non è un'immagine valida o risulta danneggiato.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

Tabella degli errori HTTP

Codice	Identificatore	Causa principale	Soluzione consigliata
`400`	`BAD_REQUEST`	Payload JSON malformato o parametri non corretti.	Correggi la formattazione del JSON inviato.
`401`	`UNAUTHORIZED`	Chiave API mancante o revocata.	Verifica l'intestazione `X-API-Key`.
`401`	`TIMESTAMP_DRIFT`	Timestamp scostato di oltre ±300 secondi.	Sincronizza l'orologio di sistema via NTP.
`401`	`INVALID_SIGNATURE`	Firma HMAC-SHA256 non corrispondente.	Rivedi il calcolo della stringa canonica e la secret key.
`403`	`FORBIDDEN`	Privilegi insufficienti per la risorsa richiesta.	Modifica i permessi della chiave dalla dashboard.
`404`	`NOT_FOUND`	La richiesta (`job_id`) o risorsa non esiste.	Verifica l'identificativo passato nell'URL.
`413`	`PAYLOAD_TOO_LARGE`	File eccedente la dimensione massima consentita dal tuo piano.	Riduci le dimensioni del file prima dell'invio.
`415`	`UNSUPPORTED_MEDIA`	Formato file non supportato.	Invia solo formati JPEG, PNG, WebP, AVIF o SVG.
`422`	`UNPROCESSABLE`	File con estensione corretta ma dati corrotti.	Accertati che il flusso di upload sia integro.
`429`	`RATE_LIMIT_EXCEEDED`	Superato il limite di richieste al secondo.	Implementa retry graduali con Exponential Backoff.
`429`	`QUOTA_EXCEEDED`	Esaurita la quota mensile di trasformazioni.	Effettua l'upgrade del piano nella dashboard.
`500`	`INTERNAL_ERROR`	Anomalia imprevista sui server di elaborazione.	Riprova la richiesta dopo un breve intervallo.
`503`	`SERVICE_UNAVAILABLE`	Manutenzione programmata o sovraccarico temporaneo.	Esegui il fallback in modalità passthrough.