Revisionato 2026-11-10 · Versione API 2026-11-09 · Leggi Markdown
Errori, ripetizioni e recupero
Gli errori API usano { "error": { "code": "…", "message": "…", "requestId": "…" } }
con errori di campo opzionali, errori di destinazione, suggerimenti di ripetizione e handoff di azioni.
Conserva requestId per il supporto. Non registrare credenziali, URL di upload firmati o
contenuto sensibile delle richieste quando raccogli la diagnostica.
| Risposta | Recupero |
|---|---|
401 unauthenticated | Verifica product key assente, malformata o revocata |
403 forbidden_scope / account_not_allowed | Rivedi gli scope della chiave e l'accesso alle destinazioni |
402 account_limit, seat_limit, storage_limit | Rivedi i diritti del workspace e l'uso delle risorse |
402 subscription_inactive / trial_expired | Risolvi lo stato di fatturazione; conserva bozze e lavoro in coda |
409 revision_conflict | Leggi la versione corrente, esamina le modifiche e riapplica intenzionalmente |
409 idempotency_conflict | La chiave è stata riutilizzata con un corpo diverso; riconcilia l'operazione originale |
409 consent_required | Chiedi a una persona autorizzata di completare l'handoff di revisione fornito |
409 too_late_to_cancel | Ispeziona lo stato effettivo della consegna; non dichiarare che la cancellazione è riuscita |
media_expired / media_deleting | Ricarica gli originali e aggiorna la bozza |
422 validation_failed | Correggi i campi strutturati o i problemi per destinazione |
429 rate_limited | Rispetta Retry-After; riduci la concorrenza e usa il backoff |
submission_unknown | Riconcilia l'esito esterno esistente prima di tentare un altro invio |
Ripetizioni sicure delle mutazioni
Genera una chiave di idempotenza prima della prima mutazione e memorizza la sua esatta richiesta.
Se la risposta si perde, l'operazione potrebbe essere già riuscita. Ripeti la
stessa richiesta con la stessa chiave; non generare mai una chiave nuova solo perché la
rete è andata in timeout. Gli strumenti MCP che mutano restituiscono la loro chiave, incluso nelle
azioni fallite con transport_outcome_unknown. L'adattatore non ripete automaticamente le mutazioni.
I limiti tecnici di velocità del workspace non sono crediti di pubblicazione. Usa /usage per il
piano corrente e le informazioni sui limiti di frequenza. Fai backoff per gli errori transitori solo quando
appropriato; ripetere errori di autorizzazione, validazione o consenso umano senza
cambiarne la causa non aiuta.
Successo parziale e osservazione
Un batch di pubblicazione/programmazione accettato è un insieme di consegne indipendenti. Conserva le ricevute riuscite e i link nativi. Recupera una destinazione fallita attraverso il suo endpoint di ripetizione invece di ricreare l'intero batch. Preferisci i webhook firmati; se fai polling, usa un numero limitato di tentativi con ritardi crescenti ed esponi il lavoro non risolto a una persona.