Fatturazione Elettronica Aruba
API Reference

Errors

Error handling, error classes, and error codes reference.

Errors

The SDK provides typed error classes for different error scenarios, making it easy to handle specific error cases in your application.

Error Classes

All error classes extend ArubaApiError, which extends the native Error class.

ArubaApiError

Base error class for all API errors.

class ArubaApiError extends Error {
  readonly code: string;      // Error code
  readonly statusCode: number; // HTTP status code
  readonly details?: string;   // Additional details
}

Example:

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

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

AuthenticationError

Thrown when authentication fails (401 Unauthorized).

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

Common causes:

  • Invalid credentials
  • Expired access token (auto-refresh failed)
  • Revoked token

Example:

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

try {
  await client.auth.signIn(username, password);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid credentials or session expired');
  }
}

RateLimitError

Thrown when rate limits are exceeded (429 Too Many Requests).

class RateLimitError extends ArubaApiError {
  readonly retryAfter?: number; // Seconds to wait before retry
  // code: 'RATE_LIMIT'
  // statusCode: 429
}

Rate limits:

EndpointLimit
Authentication1 request/minute
Invoice upload30 requests/minute
Search12 requests/minute

Example:

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

try {
  await invoices.upload({ dataFile });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
    await sleep(error.retryAfter * 1000);
    // Retry the request
  }
}

TimeoutError

Thrown when a request times out.

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

Example:

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

try {
  await invoices.findSent({ creationStartDate, creationEndDate });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Request timed out, please try again');
  }
}

NetworkError

Thrown when a network error occurs (connection failed, DNS error, etc.).

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

Example:

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

try {
  await client.auth.signIn(username, password);
} catch (error) {
  if (error instanceof NetworkError) {
    console.log('Network error - check your internet connection');
  }
}

HTTP Status Codes

StatusDescriptionSDK Behavior
400Bad RequestThrows ArubaApiError with validation details
401UnauthorizedAttempts token refresh, then throws AuthenticationError
403ForbiddenThrows ArubaApiError (missing permissions)
404Not FoundThrows ArubaApiError (resource not found)
413Payload Too LargeThrows ArubaApiError (file > 5MB)
429Too Many RequestsAuto-retry with exponential backoff, then throws RateLimitError
500Server ErrorAutomatic retry, then throws ArubaApiError

Synchronous Error Codes

Returned immediately by the API during upload operations:

CodeDescriptionAction
0000Operation completedSuccess
0001Filename already existsUse a different filename
0002Duplicate invoiceInvoice already sent
0003Space limit exceededContact Aruba for more space
0004Invalid fileCheck XML format
0005Invalid Base64 contentRe-encode the file
0006Invalid document typeCheck TipoDocumento
0007Invalid signatureRe-sign the invoice
0008Certificate expiredRenew certificate
0009Certificate revokedUse valid certificate
0010Untrusted certificateUse Aruba-approved CA
0096Service unavailableRetry later
0097Internal errorContact support
0098TimeoutRetry the request
0099Generic errorCheck request format

Asynchronous Error Codes

Received via NS (Notifica di Scarto) notification from SDI:

CodeDescriptionAction
FATRSM200File format non-compliantValidate XML against FatturaPA schema
FATRSM201Invalid transmission IDCheck progressivoInvio format
FATRSM212IdTrasmittente differs from Aruba'sUse Aruba's ID (01879020517)
FATRSM213Invalid recipient codeVerify codiceDestinatario
FATRSM214Invalid recipient PECVerify PEC address
FATRSM215Unsupported transmission formatUse FPR12 or FPA12

Complete Error Handling Example

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

async function uploadInvoiceSafely(invoices: InvoicesClient, dataFile: string) {
  try {
    const result = await invoices.upload({ dataFile });
    return { success: true, data: result };
  } catch (error) {
    if (error instanceof AuthenticationError) {
      // Session expired - re-authenticate
      return { success: false, error: 'AUTH_EXPIRED', message: 'Please login again' };
    }

    if (error instanceof RateLimitError) {
      // Rate limited - wait and retry
      return {
        success: false,
        error: 'RATE_LIMITED',
        retryAfter: error.retryAfter,
        message: `Too many requests. Retry after ${error.retryAfter}s`,
      };
    }

    if (error instanceof TimeoutError) {
      // Timeout - can retry
      return { success: false, error: 'TIMEOUT', message: 'Request timed out' };
    }

    if (error instanceof NetworkError) {
      // Network issue - check connection
      return { success: false, error: 'NETWORK', message: 'Network error' };
    }

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

    // Unknown error
    throw error;
  }
}

Type Guards

You can use instanceof to check error types:

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