Tutte le risposte dell'API seguono uno schema standardizzato per garantire coerenza e prevedibilità.
{
"status": "success",
"data": <dati della risposta>,
"meta": {
"requestId": "uuid-unico-della-richiesta",
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
{
"status": "error",
"error": {
"code": "CODICE_ERRORE",
"message": "Messaggio di errore descrittivo",
"details": {}
},
"meta": {
"requestId": "uuid-unico-della-richiesta",
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
statusIndica l'esito della richiesta:
"success" - Richiesta completata con successo"error" - Si è verificato un erroredataContiene i dati della risposta quando status è "success". Può essere:
errorPresente solo quando status è "error". Contiene:
code: Codice errore standardizzatomessage: Messaggio descrittivo dell'erroredetails: Oggetto con dettagli aggiuntivi (opzionale)metaMetadati della richiesta:
requestId: UUID univoco per tracciare la richiestatimestamp: Timestamp ISO 8601 della risposta{
"status": "success",
"data": {
"id": 123,
"name": "Esempio Organizzazione",
"tax_code": "12345678901",
"created_at": "2024-01-01T00:00:00.000Z"
},
"meta": {
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
{
"status": "success",
"data": [
{
"id": 1,
"name": "Organizzazione 1"
},
{
"id": 2,
"name": "Organizzazione 2"
}
],
"meta": {
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2024-01-15T10:30:00.000Z",
"total": 100,
"limit": 10,
"offset": 0,
"page": 1,
"totalPages": 10
}
}
{
"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"
}
},
"meta": {
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
L'API utilizza i codici di stato HTTP standard:
| Codice | Significato | Quando |
|---|---|---|
| 200 | OK | Richiesta completata con successo |
| 201 | Created | Risorsa creata con successo |
| 204 | No Content | Operazione completata senza contenuto |
| 400 | Bad Request | Richiesta malformata o non valida |
| 401 | Unauthorized | Autenticazione richiesta o non valida |
| 403 | Forbidden | Accesso negato (autorizzazione) |
| 404 | Not Found | Risorsa non trovata |
| 409 | Conflict | Conflitto con stato attuale |
| 422 | Unprocessable Entity | Validazione fallita |
| 500 | Internal Server Error | Errore interno del server |
| 503 | Service Unavailable | Servizio temporaneamente non disponibile |
Per maggiori dettagli sulla gestione degli errori, consulta:
status prima di accedere a datarequestId per tracciare problemi in produzionemessage all'utente per errori user-friendlydetails per validazione form e debuggingnull sono esplicitamente rappresentati (non omessi)[] (non null)