Questa guida ti aiuta a gestire correttamente gli errori quando utilizzi l'API Italianonprofit.
Tutti gli errori seguono lo stesso formato standardizzato:
{
"status": "error",
"error": {
"code": "CODICE_ERRORE",
"message": "Messaggio di errore descrittivo",
"details": {
"campo": "Dettaglio specifico del campo"
}
},
"meta": {
"requestId": "uuid-unico",
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
| Codice | HTTP | Descrizione |
|---|---|---|
AUTHENTICATION_REQUIRED | 401 | Token mancante o non valido |
TOKEN_EXPIRED | 401 | Token scaduto |
INVALID_TOKEN | 401 | Token non valido o malformato |
REFRESH_TOKEN_INVALID | 401 | Refresh token non valido |
| Codice | HTTP | Descrizione |
|---|---|---|
FORBIDDEN | 403 | Accesso negato |
INSUFFICIENT_PERMISSIONS | 403 | Permessi insufficienti |
SCOPE_NOT_ALLOWED | 403 | Scope API Key non permesso |
RESOURCE_OWNERSHIP_REQUIRED | 403 | Non sei proprietario della risorsa |
| Codice | HTTP | Descrizione |
|---|---|---|
VALIDATION_ERROR | 400 | Dati di input non validi |
INVALID_PARAM | 400 | Parametro non valido |
MISSING_REQUIRED_FIELD | 400 | Campo obbligatorio mancante |
INVALID_FORMAT | 400 | Formato dati non valido |
| Codice | HTTP | Descrizione |
|---|---|---|
NOT_FOUND | 404 | Risorsa non trovata |
RESOURCE_NOT_FOUND | 404 | Risorsa specifica non trovata |
CONFLICT | 409 | Conflitto con stato attuale |
DUPLICATE_RESOURCE | 409 | Risorsa già esistente |
| Codice | HTTP | Descrizione |
|---|---|---|
INTERNAL_SERVER_ERROR | 500 | Errore interno del server |
DATABASE_ERROR | 500 | Errore nel database |
SERVICE_UNAVAILABLE | 503 | Servizio temporaneamente non disponibile |
ELASTICSEARCH_UNAVAILABLE | 503 | Elasticsearch non disponibile |
async function makeRequest(url: string, options: RequestInit) {
try {
const response = await fetch(url, options);
const data = await response.json();
if (data.status === "error") {
// Gestisci errore
switch (data.error.code) {
case "AUTHENTICATION_REQUIRED":
case "TOKEN_EXPIRED":
// Riloggare o rinnovare token
await refreshToken();
break;
case "VALIDATION_ERROR":
// Mostra errori di validazione all'utente
showValidationErrors(data.error.details);
break;
case "NOT_FOUND":
// Risorsa non trovata
showNotFoundMessage();
break;
default:
// Errore generico
showErrorMessage(data.error.message);
}
throw new Error(data.error.message);
}
return data.data;
} catch (error) {
// Gestisci errori di rete o altri errori
console.error("Request failed:", error);
throw error;
}
}
import requests
def make_request(url, headers=None, data=None):
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
result = response.json()
if result.get('status') == 'error':
error = result.get('error', {})
error_code = error.get('code')
if error_code == 'AUTHENTICATION_REQUIRED':
# Riloggare o rinnovare token
refresh_token()
elif error_code == 'VALIDATION_ERROR':
# Mostra errori di validazione
print(f"Validation errors: {error.get('details')}")
else:
print(f"Error: {error.get('message')}")
raise Exception(error.get('message'))
return result.get('data')
except requests.exceptions.HTTPError as e:
print(f"HTTP error: {e}")
raise
Quando un token è scaduto, devi rinnovarlo usando il refresh token:
if (error.code === "TOKEN_EXPIRED") {
const newToken = await refreshAccessToken(refreshToken);
// Riprova la richiesta con il nuovo token
return await retryRequest(url, newToken);
}
Gli errori di validazione includono dettagli sui campi specifici:
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "I dati forniti non sono validi",
"details": {
"email": "Email non valida",
"password": "Password deve contenere almeno 8 caratteri"
}
}
}
Usa questi dettagli per mostrare errori specifici nel form:
if (error.code === "VALIDATION_ERROR" && error.details) {
Object.entries(error.details).forEach(([field, message]) => {
setFieldError(field, message);
});
}
Se superi i limiti di rate, riceverai:
{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Troppe richieste. Riprova più tardi.",
"details": {
"retryAfter": 60
}
}
}
Implementa un backoff esponenziale:
if (error.code === "RATE_LIMIT_EXCEEDED") {
const retryAfter = error.details?.retryAfter || 60;
await sleep(retryAfter * 1000);
return await retryRequest(url, options);
}
status prima di accedere a datarequestId per tracciare problemi in produzionemessagePer aiutare il debugging, ogni errore include:
requestId: UUID univoco per tracciare la richiesta nei logtimestamp: Quando si è verificato l'errorecode: Codice standardizzato per identificare il tipo di erroredetails: Informazioni aggiuntive quando disponibiliSe hai bisogno di supporto, fornisci sempre il requestId quando contatti il supporto.