--- title: "Errori" description: "L'involucro degli errori, tutti i codici e quali vale la pena riprovare." canonical: "https://atelier201.com/docs/it/api/errors" updated: "2026-11-06" --- # Errori Tutti gli errori hanno la stessa struttura: ```json { "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_revision` indica la revisione da leggere e `details.paths` elenca 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_url` rimanda 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'.