Codici di Errore

Comprendere le risposte di errore dell'API e come gestirle.

Panoramica

L'API restituisce risposte di errore standardizzate con codici di errore specifici per aiutarti a identificare e risolvere rapidamente i problemi.

Formato della Risposta di Errore

Tutte le risposte di errore seguono questa struttura:

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Credenziali di autenticazione mancanti",
    "details": "I campi 'username' e 'password' sono entrambi obbligatori",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Campo	Tipo	Descrizione
`status`	string	Sempre "error" per le risposte di errore
`error.code`	string	Identificatore univoco dell'errore
`error.message`	string	Messaggio di errore leggibile
`error.details`	string	Contesto aggiuntivo (opzionale)
`error.timestamp`	string	Timestamp ISO 8601

Errori di Autenticazione (1000-1099)

Errori relativi alle credenziali e all'autenticazione.

Codice	HTTP	Messaggio	Soluzione
`AUTH_1001`	401	Credenziali di autenticazione mancanti	Includi sia username che password nella richiesta
`AUTH_1002`	401	Username o password non validi	Verifica che le credenziali siano corrette
`AUTH_1003`	403	Account temporaneamente bloccato	Attendi prima di riprovare o contatta il supporto

Errori di Quota (1100-1199)

Errori relativi alla quota API e ai limiti di utilizzo.

Codice	HTTP	Messaggio	Soluzione
`QUOTA_1101`	403	Quota API insufficiente	Acquista più crediti o controlla la quota
`QUOTA_1102`	429	Quota API superata	Attendi il ripristino della quota o aggiorna il piano

Errori di Validazione (2000-2099)

Errori relativi alla validazione della richiesta e ai dati di input.

Codice	HTTP	Messaggio	Soluzione
`VAL_2001`	400	Nessun file caricato	Includi un file nella richiesta
`VAL_2002`	400	Formato file non valido	Usa formati supportati: PDF, PNG, JPG, WEBP
`VAL_2003`	400	File PDF multipli non consentiti	Carica un singolo PDF o più immagini
`VAL_2004`	400	PDF e immagini non possono essere combinati	Carica o PDF o immagini, non entrambi
`VAL_2005`	400	Codice lingua non supportato	Usa un codice lingua supportato

Errori di Elaborazione (3000-3099)

Errori durante l'elaborazione del documento e l'analisi AI.

Codice	HTTP	Messaggio	Soluzione
`PROC_3001`	500	Elaborazione documento fallita	Controlla la qualità dell'immagine, riprova la richiesta
`PROC_3002`	500	Estrazione metadati fallita	Assicurati che il documento contenga testo leggibile
`PROC_3003`	500	Estrazione parametri fallita	Verifica che il formato dell'esame del sangue sia riconoscibile
`PROC_3004`	500	Generazione interpretazione fallita	Riprova la richiesta
`PROC_3006`	504	Timeout di elaborazione	Riduci la dimensione del file o dividi in più richieste
`PROC_3007`	500	Analisi fallita dopo vari tentativi	Attendi e riprova, o contatta il supporto

Errori del Server (5000-5099)

Errori interni del server e problemi di disponibilità del servizio.

Codice	HTTP	Messaggio	Soluzione
`SRV_5001`	500	Errore interno del server	Riprova la richiesta, contatta il supporto se persiste
`SRV_5002`	503	Servizio temporaneamente non disponibile	Attendi e riprova con backoff esponenziale

Best Practice per la Gestione degli Errori

Raccomandazioni

Controlla sempre il campo status - Le risposte di successo hanno "status": "success"
Implementa la logica di retry per errori transitori (5xx) con backoff esponenziale
Registra i codici di errore per debug e monitoraggio
Mostra messaggi user-friendly basati sui codici di errore
Usa gli endpoint sandbox per testare la gestione degli errori

Esempio di Gestione Errori (JavaScript)

async function analyzeBloodTest(file) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      body: formData
    });

    const data = await response.json();

    if (data.status === 'error') {
      const errorCode = data.error.code;

      switch (true) {
        case errorCode.startsWith('AUTH_'):
          throw new Error('Autenticazione fallita. Controlla le credenziali.');
        case errorCode.startsWith('QUOTA_'):
          throw new Error('Quota superata. Aggiorna il tuo piano.');
        case errorCode.startsWith('VAL_'):
          throw new Error('Richiesta non valida: ' + data.error.message);
        case errorCode.startsWith('PROC_'):
          // Riprova per errori di elaborazione
          return retryRequest(file);
        default:
          throw new Error('Si è verificato un errore. Riprova.');
      }
    }

    return data.data;
  } catch (error) {
    console.error('Errore API:', error);
    throw error;
  }
}