Gestione degli errori

L'API di Meirra usa i codici di stato HTTP convenzionali per indicare il successo o il fallimento delle richieste. In generale: • **2xx** – Successo. La richiesta ha funzionato come previsto. • **4xx** – Errore lato client. La richiesta non è valida o non può essere servita. • **5xx** – Errore lato server. Qualcosa è andato storto da parte nostra. Tutte le risposte di errore usano una struttura JSON coerente con codice, messaggio e dettagli utili per diagnosticare e gestire il problema.

Tutti gli errori seguono un formato coerente: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Descrizione leggibile dell'errore", "details": { ... } } } ``` Il campo `code` è un codice leggibile dalla macchina che puoi usare nella tua logica di gestione errori. Il `message` offre una descrizione leggibile da una persona. L'oggetto opzionale `details` aggiunge contesto specifico al tipo di errore.

Gli errori di autenticazione si verificano quando la chiave API manca, non è valida o non ha i permessi. | Codice | HTTP | Descrizione | |--------|------|-------------| | `INVALID_API_KEY` | 401 | Chiave API mancante o non valida | | `API_KEY_REVOKED` | 401 | Chiave API revocata | | `IP_NOT_ALLOWED` | 403 | IP della richiesta non in lista permessi | **Esempio:** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "La chiave API fornita non è valida o manca" } } ``` **Come risolvere:** Verifica che la chiave API sia corretta e inclusa nell'intestazione `x-api-key`. Controlla nel Pannello sviluppatori se la chiave è stata revocata.

Gli errori di saldo si verificano quando il tuo account non ha crediti sufficienti per la richiesta. | Codice | HTTP | Descrizione | |--------|------|-------------| | `INSUFFICIENT_BALANCE` | 402 | Saldo troppo basso per la richiesta | **Esempio:** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Il tuo saldo di $0.50 è insufficiente per questa richiesta ($1.00 richiesti)", "details": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **Come risolvere:** Ricarica il saldo del tuo account dal Pannello sviluppatori. Valuta di impostare avvisi di saldo basso per evitare interruzioni.

Gli errori di limite di utilizzo si verificano quando superi la frequenza di richieste consentita. | Codice | HTTP | Descrizione | |--------|------|-------------| | `RATE_LIMIT_EXCEEDED` | 429 | Troppe richieste | **Esempio:** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Limite di utilizzo superato. Riprova tra 60 secondi.", "details": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **Come risolvere:** Implementa un backoff esponenziale. Controlla l'intestazione `Retry-After` per sapere quando riprovare. Distribuisci le richieste nel tempo.

Gli errori di validazione si verificano quando i parametri della richiesta mancano o non sono validi. | Codice | HTTP | Descrizione | |--------|------|-------------| | `INVALID_REQUEST` | 400 | Parametri mancanti o non validi | | `INVALID_EMAIL` | 400 | Formato email non valido | | `BATCH_TOO_LARGE` | 400 | Il batch supera la dimensione massima | **Esempio:** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Validazione della richiesta fallita", "details": { "field": "email", "issue": "L'email è obbligatoria" } } } ``` **Come risolvere:** Controlla il campo `details` per identificare l'errore di validazione specifico. Assicurati di fornire tutti i campi obbligatori nel formato atteso.

Gli errori di servizio si verificano quando qualcosa va storto nella nostra infrastruttura. | Codice | HTTP | Descrizione | |--------|------|-------------| | `SERVICE_ERROR` | 500 | Fallimento interno del servizio | | `SERVICE_UNAVAILABLE` | 503 | Servizio temporaneamente non disponibile | | `UPSTREAM_ERROR` | 502 | Una dipendenza esterna è fallita | **Esempio:** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "Si è verificato un errore interno. Riprova più tardi." } } ``` **Come risolvere:** Sono errori transitori. Implementa una logica di retry con backoff esponenziale. Se gli errori persistono, controlla la pagina di stato o contatta il supporto.