Errori
Ogni errore dell'API di vokse arriva in un formato JSON coerente, con un codice stabile leggibile da una macchina, un messaggio per le persone e dettagli strutturati facoltativi. Programma sul codice, mostra il messaggio.
Il formato dell'errore
Le risposte diverse da 2xx hanno questa forma. Lo stato HTTP ti dice la classe; error.code ti dice esattamente cos'è successo. details è un oggetto facoltativo e traceId identifica la richiesta nei nostri log.
{ "error": { "code": "SCOPE_DENIED", "message": "API key is missing required scopes: write:transactions", "details": { "requiredScopes": ["write:transactions"], "grantedScopes": ["read:transactions"], "missing": ["write:transactions"] }, "traceId": "01J8MEB4W2Q0F7GXK3N5D8C1VZ" }}Codici comuni
Questi sono i codici che ti capiterà di gestire più spesso:
INVALID_REQUEST | 422 | Il corpo o la query della richiesta non ha superato la validazione Zod. details.issues elenca ogni campo non valido. |
UNAUTHORIZED | 401 | Header Authorization mancante o malformato. |
SCOPE_DENIED | 403 | La chiave è valida ma non ha lo scope richiesto da questo endpoint. |
API_KEY_NOT_ALLOWED | 403 | Questo endpoint è riservato alla sessione e non si può chiamare con una chiave API. |
API_KEY_EXPIRED | 401 | La chiave ha superato la data di scadenza. Ruotala. |
NOT_FOUND | 404 | La risorsa non esiste oppure non è visibile a questa famiglia. |
IDEMPOTENCY_KEY_REUSED | 409 | Un'Idempotency-Key è stata riusata con un corpo di richiesta diverso. |
RATE_LIMITED | 429 | Troppe richieste. Rallenta e riprova dopo il tempo indicato da Retry-After. |
Leggere details
Per INVALID_REQUEST, details.issues contiene le issue di Zod: una voce per ogni campo non valido, con il suo percorso e il messaggio. Considera error.code come il contratto e error.message come testo da mostrare, che può cambiare; cita il traceId quando scrivi all'assistenza.