Errori
L'involucro degli errori, tutti i codici e quali vale la pena riprovare.
Tutti gli errori hanno la stessa struttura:
{
"error": {
"type": "not_found_error",
"code": "resource_not_found",
"message": "This site does not exist.",
"docs_url": "https://atelier201.com/docs/api/errors#resource_not_found"
},
"request_id": "req_01K9X7"
}Gestisci gli errori in base a code, mai a message. I codici fanno parte del contratto; i messaggi sono pensati per le persone e possono essere migliorati nel tempo. Alcuni errori includono un oggetto details con le informazioni necessarie per intervenire, ad esempio la revisione attuale dopo un conflitto di scrittura.
Quando riprovare
| Status | Riprovare? |
|---|---|
| 429 | Sì, dopo Retry-After. |
| 5xx | Solo per una richiesta idempotente (GET, PUT, DELETE). Un POST che restituisce un errore 5xx potrebbe essere già stato applicato. Prima leggi di nuovo la risorsa. |
| 4xx | No. La richiesta non è corretta e non lo sarà nemmeno riprovandola. |
Tutti i codici
authentication_required
authentication_error · HTTP 401
Non è stata inviata alcuna credenziale. Aggiungi un’intestazione Authorization: Bearer.
invalid_api_key
authentication_error · HTTP 401
La credenziale non è riconosciuta. Potrebbe appartenere a un’area di lavoro che non esiste più.
api_key_expired
authentication_error · HTTP 401
La chiave ha superato la data di scadenza. Creane una nuova.
api_key_revoked
authentication_error · HTTP 401
Qualcuno ha revocato la chiave. La revoca è permanente.
insufficient_scope
permission_error · HTTP 403
La credenziale è valida, ma non dispone dell’ambito richiesto da questo endpoint. Il messaggio indica quale. Emetti di nuovo la credenziale: non è possibile estenderne l’ambito.
feature_not_available
permission_error · HTTP 403
Il piano non include questa funzionalità. Quando provi a pubblicare una bozza, details.blockers contiene plan_required e action_url apre la pagina del piano del sito.
admin_required
permission_error · HTTP 403
L’azione è riservata agli amministratori dell’area di lavoro: pubblicare, ripristinare una versione precedente, mettere un sito offline, eliminare un sito e modificarne i domini.
invalid_request
invalid_request_error · HTTP 400
Il corpo o la query non ha superato la convalida. Il messaggio indica il campo interessato.
unknown_field
invalid_request_error · HTTP 400
È stato inviato un campo non accettato da questo endpoint. Gli input sono volutamente rigorosi: ignorare un campo senza segnalarlo sarebbe un bug che potresti scoprire molto più avanti.
invalid_parameter
invalid_request_error · HTTP 400
Un parametro ha un formato errato, di solito perché l’ID non è valido.
invalid_cursor
invalid_request_error · HTTP 400
Il cursore di paginazione non è stato emesso da noi. Ricomincia l’elenco.
request_too_large
invalid_request_error · HTTP 413
Il corpo supera il limite massimo.
resource_not_found
not_found_error · HTTP 404
L’oggetto non esiste in QUESTA area di lavoro. Anche una risorsa appartenente a un’altra area di lavoro restituisce questo errore, appositamente: distinguerle permetterebbe di scoprire quali ID esistono.
conflict
conflict_error · HTTP 409
La risorsa esiste e la richiesta è ben formata, ma il suo stato attuale non consente l’azione. A differenza di un errore 400, l’operazione potrebbe riuscire in seguito. Cause comuni:
- Conflitto di scrittura. Qualcuno ha modificato un file da quando lo hai letto.
details.reasonèrevision_conflict,details.current_revisionindica la revisione da leggere edetails.pathselenca ogni file con l’hash previsto e quello rilevato. - Pubblicazione basata su una revisione non aggiornata oppure build che non può essere pubblicata. Ripeti la revisione e leggi
details.blockers. - Limite del piano, ad esempio troppe bozze o un dominio non incluso nel piano. Il messaggio indica il limite e
action_urlrimanda alla pagina da cui è possibile aumentarlo.
result_not_ready
conflict_error · HTTP 409
L’operazione non è ancora terminata, ad esempio perché un sito è ancora in fase di creazione. Attendi qualche secondo prima di riprovare.
idempotency_key_reused
conflict_error · HTTP 409
La Idempotency-Key inviata a un endpoint che la accetta è già stata usata per una richiesta diversa in questa area di lavoro. Non è stata eseguita alcuna operazione. Usa una nuova chiave per una nuova operazione; se invii di nuovo la stessa richiesta con la stessa chiave, riceverai la prima risposta.
insufficient_credits
invalid_request_error · HTTP 402
Crediti insufficienti. Interrompi l’operazione e avvisa una persona: riprovare non servirà.
request_too_large_for_plan
invalid_request_error · HTTP 422
Il corpo rientra nel limite massimo, ma supera quello consentito dal piano.
result_expired
not_found_error · HTTP 410
Il risultato è stato eliminato secondo la policy di conservazione. Non sarà ripristinato.
rate_limited
rate_limit_error · HTTP 429
Troppe richieste. Attendi il periodo indicato da Retry-After prima di riprovare. Lo stesso intervallo è riportato nel corpo come dato: details.retry_after_seconds e details.retry_at (una data ISO), oltre che negli errori degli strumenti MCP e nell’output JSON della CLI.
internal_error
api_error · HTTP 500
Si è verificato un errore da parte nostra. Indica il request_id.
service_unavailable
api_error · HTTP 503
Un servizio da cui dipendiamo non è disponibile o è in manutenzione. Riprova dopo un po’.