Codici di errore

Una sola busta per tutti i fallimenti:

{ "error": { "code": "invalid_request", "message": "…" } }

HTTP	code	Quando	Che fare
401	missing_api_key	Nessun header Authorization: Bearer sk_… né X-API-Key	Aggiunga la chiave
401	invalid_api_key	Chiave revocata, sconosciuta o conto inattivo	Verifichi la chiave e lo stato del conto
403	insufficient_scope	La chiave non ha quel diritto (pagare, per esempio)	Emetta una chiave con l'ambito giusto
403	client_inactive	Il conto non è validato, o è sospeso	Completi la pratica KYB
403	not_live	Conto non ancora aperto alla modalità reale	Usi una chiave sk_test_ nel frattempo
404	not_found	Risorsa inesistente — o non sua	Verifichi l'identificativo
409	already_exists	Doppione (riferimento già usato)	Rilegga la risorsa esistente
409	precondition_failed	Lo stato non permette l'operazione	Consulti la risorsa, corregga la sequenza
409	concurrent_request	Stesso Idempotency-Key, corpo diverso	Non riusi una chiave per due operazioni
422	invalid_request	Corpo non valido (campo, importo, asset)	Il message nomina il campo in errore
422	insufficient_funds	Saldo insufficiente per questo pagamento	Consulti GET /v1/balances
429	—	300 richieste/minuto superate	Rispetti l'header Retry-After
502	upstream_error	Una dipendenza è fallita	Ripeta con lo stesso Idempotency-Key
503	temporarily_unavailable	Indisponibilità passeggera	Ripeta con backoff

Ripetere senza rischio

I 502 e i 503 si ripetono sempre con lo stesso Idempotency-Key: se la prima richiesta era andata a buon fine lato server, lei ne recupera il risultato invece di creare un doppione.

Un 502 non vuol dire che non sia successo nulla. Dice che una dipendenza non ha risposto, non che l'operazione non esista. È esattamente la situazione per cui esiste l'idempotenza: ripeta, non ricrei.

not_found su una risorsa che esiste

L'API risponde 404 anche quando la risorsa appartiene a un altro esercente: non deduca mai l'esistenza di una risorsa da un 404.

Un corpo rifiutato non è un campo ignorato

Un campo sconosciuto in un corpo JSON è ignorato in silenzio, non rifiutato. Un refuso nel nome di un campo facoltativo non produce quindi alcun errore: produce un'operazione creata senza ciò che credeva di aver inviato. Rilegga i nomi nel riferimento invece di affidarsi all'assenza di un 422.