Non riprovare mai
invalid_request, invalid_amount, unknown_asset_or_rail, asset_not_offered, unauthorized. La richiesta è in errore: riprovarla invariata dà lo stesso risultato. Correggila, o mostra il motivo.
Developers
Catalogo degli errori
Ogni errore porta un codice stabile, leggibile dalla macchina e uno stato HTTP coerente. Il codice è ciò su cui la tua integrazione dovrebbe basarsi: il testo può evolversi, il codice no.
Forma di un errore
La forma attuale è volutamente minima. È stabile, ed è ciò che conta: un codice, e niente che riveli un dettaglio interno.
{ "error": "rate_stale" }{
"error": "rail_not_open",
"reason": {
"fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
"en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
}
}Alcuni errori portano un oggetto motivo bilingue, pensato per essere mostrato così com'è all'utente. Un circuito chiuso è uno di questi: il motivo spiega un vincolo normativo nominato, non un'interruzione, e mostrarlo evita una richiesta di supporto. L'API versionata aggiungerà un id di richiesta a questo involucro, così puoi indicarci una riga precisa nei nostri log.
Codici in vigore
Questi codici sono restituiti oggi dall'endpoint di preventivo.
| code | HTTP | Cosa significa | Cosa fare |
|---|---|---|---|
invalid_request | 400 | Il corpo della richiesta non supera la validazione dello schema: campo mancante, tipo errato, valore fuori dai limiti consentiti. | Controlla che l'importo sia una stringa e non un numero, e che la direzione sia esattamente "sell" o "receive". |
invalid_amount | 400 | L'importo non può essere analizzato o ha più decimali di quanto l'asset o la valuta accettino. | Tronca alla precisione dell'unità: 6 decimali per USDT, 8 per BTC, 2 per l'euro, 0 per il franco CFA. |
unknown_asset_or_rail | 404 | L'identificatore dell'asset o del canale non esiste nel catalogo. | Gli identificatori sono stabili e non vengono mai riassegnati. Ricarica il catalogo piuttosto che indovinarli. |
rail_not_open | 409 | Il canale esiste ma non è aperto. La risposta riporta il motivo esatto, in entrambe le lingue. | Mostra il motivo così com'è: spiega un vincolo normativo, non un'interruzione. Offri un canale aperto nello stesso paese. |
asset_not_offered | 409 | L'asset è nel catalogo ma non è offerto: il caso degli asset ad anonimato potenziato. | Non offrirlo nel tuo selettore. Il catalogo lo restituisce con il suo motivo così puoi spiegarlo. |
rate_stale | 503 | L'ultimo prezzo noto supera l'età massima tollerata. Il motore rifiuta di quotare piuttosto che servire un prezzo obsoleto come fermo. | Riprova dopo alcuni secondi. Non memorizzare nella cache l'ultima preventiva riuscita per colmare il vuoto: sarebbe esattamente l'errore che questo codice previene. |
rate_unavailable | 503 | Nessun prezzo disponibile per questa coppia asset/valuta. | Disabilita la coppia nella tua interfaccia piuttosto che mostrare una stima. Una stima mostrata diventa un'aspettativa. |
quote_failed | 500 | Errore imprevisto durante il calcolo. Nessuna preventiva viene restituita. | Riprova una volta; se l'errore persiste, scrivici con il timestamp esatto della chiamata. |
Codici dal contratto pubblicato
Questi codici accompagnano endpoint non ancora aperti. Sono pubblicati così la gestione degli errori è scritta una volta sola.
| code | HTTP | Cosa significa | Cosa fare |
|---|---|---|---|
unauthorized | 401 | Chiave mancante, revocata o utilizzata nell'ambiente sbagliato. | Una chiave sk_test_ non funziona in produzione, e nemmeno il contrario: è voluto. |
idempotency_conflict | 409 | La stessa chiave di idempotenza è già stata utilizzata con un corpo di richiesta diverso. | Una chiave appartiene a un intento. Se il contenuto cambia, la chiave cambia; altrimenti non c'è modo di sapere quale dei due ordini riprodurre. |
quote_expired | 409 | La quotazione ha superato la sua finestra di blocco. | Richiedi una nuova quotazione e fai accettare il nuovo importo. Non ritariffiamo mai silenziosamente a scapito del cliente. |
beneficiary_rejected | 422 | I dettagli del beneficiario non superano la validazione del circuito: checksum non valido, formato non conforme o nome che non corrisponde all'identità verificata. | La risposta indica il campo problematico. Il nome del beneficiario deve essere l'identità verificata: nessun pagamento a terzi è possibile. |
country_not_served | 451 | Il paese di destinazione non è servito: sanzioni, misure restrittive o assenza di un quadro normativo locale. | Il codice 451 è scelto deliberatamente rispetto a un 404: quando rifiutiamo, diciamo che è un rifiuto e perché. |
rate_limited | 429 | Troppe chiamate nella finestra scorrevole. | Rispetta l'header Retry-After. Le quotazioni sono economiche da accodare, costose da martellare. |
not_found | 404 | La risorsa non esiste o non appartiene alla tua chiave. | Entrambi i casi restituiscono lo stesso codice: una risposta che li distinguesse permetterebbe a chiunque di enumerare i riferimenti altrui. |
Cosa non è un errore
Un importo fuori dai limiti del circuito restituisce un preventivo valido, con un oggetto limitError. Non è un fallimento: è un'informazione che la tua interfaccia dovrebbe mostrare.
"limitError": { "code": "below_min", "limit": "20.00" }Trattare questo caso come un errore HTTP ti priverebbe dell'importo calcolato, e quindi della capacità di dire all'utente “ti mancano 16,53 EUR al minimo per questo metodo di pagamento”. Il limite si applica all'importo netto, quello che riceve il beneficiario.
Riprova, o no
Tre famiglie, tre comportamenti. Riprovare un errore di validazione in un ciclo riempie solo i tuoi log.
Riprova con backoff
rate_stale, rate_unavailable, quote_failed, e qualsiasi limitazione della frequenza. Aspetta qualche secondo, con un intervallo crescente tra i tentativi. Non riempire l'intervallo con un preventivo memorizzato nella cache.
Chiedi una decisione
rail_not_open, quote_expired, beneficiary_rejected, country_not_served. La situazione richiede una scelta umana: offri un altro circuito, un preventivo aggiornato, dettagli corretti.