Errori

Gli errori usano i codici di stato HTTP e un body JSON con un code stabile e leggibile dalle macchine, un messaggio per le persone e l’ID della richiesta.

402 application/json

{
  "error": {
    "code": "quota_exceeded",
    "message": "This organisation has used all 1,000 marks of this month on its plan. Upgrade the plan for more, or wait for the 1st of next month (UTC).",
    "request_id": "req_7Hc2kQm0Zt1L"
  }
}

Basa la logica su code, mai su message: i codici fanno parte dell’API v1 e non cambieranno; i messaggi potranno diventare più chiari. Ogni risposta, riuscita o no, riporta lo stesso ID nel suo header X-Request-Id. Indicalo quando ci scrivi.

Codici

Codici di errore
Stato	Codice	Significato	Cosa fare
400	`invalid_request`	La richiesta è malformata o un campo è fuori intervallo.	Correggi la richiesta; il messaggio indica il campo.
400	`unknown_field`	Un campo che l’endpoint non conosce.	Verifica che il nome del campo sia scritto come nel riferimento.
400	`option_not_available`	Un’opzione in programma, non ancora disponibile.	Per ora omettila; le note di rilascio diranno quando arriva.
401	`missing_api_key`	Nessuna chiave bearer nell’header Authorization.	Invia Authorization: Bearer sk_….
401	`invalid_api_key`	La chiave non è una delle nostre.	Controlla la chiave; creane una nuova se l’hai persa.
401	`api_key_revoked`	La chiave è stata revocata o il suo progetto eliminato.	Usa un’altra chiave.
402	`quota_exceeded`	La quota del mese è esaurita.	Attendi il primo del mese (UTC) o passa a un piano superiore.
403	`insufficient_scope`	Alla chiave manca l’ambito di questo endpoint.	Usa una chiave con quell’ambito, oppure creane una.
403	`ip_not_allowed`	L’indirizzo non è nella lista di IP consentiti della chiave.	Chiama da un indirizzo consentito, oppure aggiorna la lista di IP consentiti.
403	`key_not_allowed_in_url`	Una chiave con ambiti oltre a tsa è stata inviata in un URL.	Usa una chiave con il solo ambito tsa e ruota quella che hai inviato.
404	`not_found`	Nessun endpoint a questo percorso.	Controlla il percorso e la versione dell’API.
404	`upload_not_found`	L’upload indicato in «upload» non è utilizzabile da questa chiave: sconosciuto, già usato, più vecchio di un’ora o creato da un’altra chiave.	Crea un nuovo upload con questa chiave (POST /v1/uploads).
405	`method_not_allowed`	L’endpoint non accetta questo metodo.	Vedi l’header Allow.
413	`payload_too_large`	Il body supera il limite dell’endpoint.	4 MB per richiesta: invia i file più grandi (fino a 25 MB) tramite POST /v1/uploads. 4 KB per le richieste di marca temporale.
415	`unsupported_media_type`	Il file o il Content-Type della richiesta non è accettato.	Invia PNG, JPEG o WebP come multipart/form-data.
422	`content_blocked`	POST /v1/mark: il controllo di sicurezza ha bloccato l’immagine; non è stato marcato nulla. Il campo «safety» del body spiega perché.	Non riprovare con la stessa immagine. I controlli eseguiti contano; la marcatura no.
429	`rate_limited`	Troppe chiamate in questo minuto per questa chiave.	Attendi i secondi indicati in Retry-After, poi riprova.
500	`internal_error`	Qualcosa non ha funzionato da parte nostra.	Riprova con backoff; non è stato addebitato nulla.
502	`mark_failed`	Non è stato possibile marcare e verificare il file; non è stato restituito alcun file.	Riprova una volta; se il problema persiste, contatta l’assistenza indicando l’ID della richiesta.
503	`marker_unavailable`	Il servizio di marcatura è momentaneamente non disponibile.	Riprova con backoff; non è stato addebitato nulla.
503	`tsa_unavailable`	Il server di marca temporale è momentaneamente non disponibile.	Riprova con backoff; non è stato addebitato nulla.
503	`storage_unavailable`	Gli upload sono momentaneamente non disponibili.	Riprova con backoff; non è stato addebitato nulla e l’upload viene conservato.

Nuovi tentativi

429: attendi il numero di secondi indicato in Retry-After.
500, 502, 503: riprova con backoff esponenziale (1 s, 2 s, 4 s…), al massimo qualche volta. Le chiamate non riuscite non vengono mai conteggiate nella tua quota.
Altri 4xx: non riprovare senza modifiche; correggi prima la richiesta.