Fatturazione Elettronica Aruba
Riferimento API

Errori

Gestione errori, classi di errore e riferimento codici errore.

Errori

L'SDK fornisce classi di errore tipizzate per diversi scenari, rendendo facile gestire casi specifici nella tua applicazione.

Classi di Errore

Tutte le classi di errore estendono ArubaApiError, che estende la classe nativa Error.

ArubaApiError

Classe base per tutti gli errori API.

class ArubaApiError extends Error {
  readonly code: string;      // Codice errore
  readonly statusCode: number; // Codice stato HTTP
  readonly details?: string;   // Dettagli aggiuntivi
}

Esempio:

import { ArubaApiError } from '@fatturazione-elettronica-aruba/core';

try {
  await invoices.upload({ dataFile });
} catch (error) {
  if (error instanceof ArubaApiError) {
    console.log(`Errore [${error.code}]: ${error.message}`);
    console.log(`Stato HTTP: ${error.statusCode}`);
    if (error.details) {
      console.log(`Dettagli: ${error.details}`);
    }
  }
}

AuthenticationError

Lanciato quando l'autenticazione fallisce (401 Unauthorized).

class AuthenticationError extends ArubaApiError {
  // code: 'AUTH_ERROR'
  // statusCode: 401
}

Cause comuni:

  • Credenziali non valide
  • Access token scaduto (auto-refresh fallito)
  • Token revocato

Esempio:

import { AuthenticationError } from '@fatturazione-elettronica-aruba/core';

try {
  await client.auth.signIn(username, password);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Credenziali non valide o sessione scaduta');
  }
}

RateLimitError

Lanciato quando i limiti di richieste sono superati (429 Too Many Requests).

class RateLimitError extends ArubaApiError {
  readonly retryAfter?: number; // Secondi da attendere prima del retry
  // code: 'RATE_LIMIT'
  // statusCode: 429
}

Limiti di rate:

EndpointLimite
Autenticazione1 richiesta/minuto
Upload fatture30 richieste/minuto
Ricerca12 richieste/minuto

Esempio:

import { RateLimitError } from '@fatturazione-elettronica-aruba/core';

try {
  await invoices.upload({ dataFile });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limit. Riprova tra ${error.retryAfter} secondi`);
    await sleep(error.retryAfter * 1000);
    // Riprova la richiesta
  }
}

TimeoutError

Lanciato quando una richiesta va in timeout.

class TimeoutError extends ArubaApiError {
  // code: 'TIMEOUT'
  // statusCode: 408
}

Esempio:

import { TimeoutError } from '@fatturazione-elettronica-aruba/core';

try {
  await invoices.findSent({ creationStartDate, creationEndDate });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Richiesta in timeout, riprova');
  }
}

NetworkError

Lanciato quando si verifica un errore di rete (connessione fallita, errore DNS, ecc.).

class NetworkError extends ArubaApiError {
  // code: 'NETWORK_ERROR'
  // statusCode: 0
}

Esempio:

import { NetworkError } from '@fatturazione-elettronica-aruba/core';

try {
  await client.auth.signIn(username, password);
} catch (error) {
  if (error instanceof NetworkError) {
    console.log('Errore di rete - controlla la connessione internet');
  }
}

Codici Stato HTTP

StatusDescrizioneComportamento SDK
400Bad RequestLancia ArubaApiError con dettagli validazione
401UnauthorizedTenta refresh token, poi lancia AuthenticationError
403ForbiddenLancia ArubaApiError (permessi mancanti)
404Not FoundLancia ArubaApiError (risorsa non trovata)
413Payload Too LargeLancia ArubaApiError (file > 5MB)
429Too Many RequestsAuto-retry con backoff esponenziale, poi RateLimitError
500Server ErrorRetry automatico, poi lancia ArubaApiError

Codici Errore Sincroni

Restituiti immediatamente dalle API durante le operazioni di upload:

CodiceDescrizioneAzione
0000Operazione effettuataSuccesso
0001Nome file già presenteUsa un nome file diverso
0002Fattura duplicataFattura già inviata
0003Superato limite spazioContatta Aruba per più spazio
0004File non validoControlla formato XML
0005Contenuto Base64 non validoRicodifica il file
0006Tipo documento non validoControlla TipoDocumento
0007Firma non validaRifirma la fattura
0008Certificato scadutoRinnova certificato
0009Certificato revocatoUsa certificato valido
0010Certificato non attendibileUsa CA approvata da Aruba
0096Servizio non disponibileRiprova più tardi
0097Errore internoContatta supporto
0098TimeoutRiprova la richiesta
0099Errore genericoControlla formato richiesta

Codici Errore Asincroni

Ricevuti tramite notifica NS (Notifica di Scarto) dallo SDI:

CodiceDescrizioneAzione
FATRSM200File non conforme al formatoValida XML contro schema FatturaPA
FATRSM201Identificativo trasmissione non validoControlla formato progressivoInvio
FATRSM212IdTrasmittente diverso da quello ArubaUsa ID Aruba (01879020517)
FATRSM213Codice destinatario non validoVerifica codiceDestinatario
FATRSM214PEC destinatario non validaVerifica indirizzo PEC
FATRSM215Formato trasmissione non supportatoUsa FPR12 o FPA12

Esempio Completo Gestione Errori

import {
  ArubaApiError,
  AuthenticationError,
  RateLimitError,
  TimeoutError,
  NetworkError,
} from '@fatturazione-elettronica-aruba/core';

async function uploadFatturaSicuro(invoices: InvoicesClient, dataFile: string) {
  try {
    const result = await invoices.upload({ dataFile });
    return { success: true, data: result };
  } catch (error) {
    if (error instanceof AuthenticationError) {
      // Sessione scaduta - ri-autenticare
      return { success: false, error: 'AUTH_EXPIRED', message: 'Effettua nuovamente il login' };
    }

    if (error instanceof RateLimitError) {
      // Rate limit - attendi e riprova
      return {
        success: false,
        error: 'RATE_LIMITED',
        retryAfter: error.retryAfter,
        message: `Troppe richieste. Riprova tra ${error.retryAfter}s`,
      };
    }

    if (error instanceof TimeoutError) {
      // Timeout - può riprovare
      return { success: false, error: 'TIMEOUT', message: 'Richiesta in timeout' };
    }

    if (error instanceof NetworkError) {
      // Problema di rete - controlla connessione
      return { success: false, error: 'NETWORK', message: 'Errore di rete' };
    }

    if (error instanceof ArubaApiError) {
      // Errore API con codice
      return {
        success: false,
        error: error.code,
        message: error.message,
        details: error.details,
      };
    }

    // Errore sconosciuto
    throw error;
  }
}

Type Guards

Puoi usare instanceof per controllare i tipi di errore:

function isRetryable(error: unknown): boolean {
  if (error instanceof RateLimitError) return true;
  if (error instanceof TimeoutError) return true;
  if (error instanceof NetworkError) return true;
  if (error instanceof ArubaApiError && error.statusCode >= 500) return true;
  return false;
}

Invoices

Package @fatturazione-elettronica-aruba/invoices

XML Builder

Package @fatturazione-elettronica-aruba/xml-builder