> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taprails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Types

> NFCPaymentError and APIError classes and their error code enums.

## NFCPaymentError

Thrown by NFC operations when something goes wrong at the device/hardware layer.

```ts theme={null}
class NFCPaymentError extends Error {
  name: 'NFCPaymentError';
  code: NFCErrorCode;
  message: string;
}
```

### NFCErrorCode

```ts theme={null}
enum NFCErrorCode {
  NOT_SUPPORTED  = 'NFC_NOT_SUPPORTED',   // No NFC hardware
  NOT_ENABLED    = 'NFC_NOT_ENABLED',     // NFC disabled in settings
  READ_FAILED    = 'READ_FAILED',         // Hardware read failure
  WRITE_FAILED   = 'WRITE_FAILED',        // HCE emulation failed
  INVALID_DATA   = 'INVALID_DATA',        // Bad/expired/forged payload
  USER_CANCELLED = 'USER_CANCELLED',      // User dismissed NFC sheet
  API_ERROR      = 'API_ERROR',           // Backend error in NFC flow
  NETWORK_ERROR  = 'NETWORK_ERROR',       // No connection in NFC flow
  TIMEOUT        = 'TIMEOUT',            // 30s scan timeout
  UNAUTHORIZED   = 'UNAUTHORIZED',        // Invalid API key
}
```

### Type guard

```ts theme={null}
import { NFCPaymentError, NFCErrorCode } from '@taprails/tap-to-pay';

if (err instanceof NFCPaymentError) {
  switch (err.code) {
    case NFCErrorCode.TIMEOUT:
      // ...
  }
}
```

***

## APIError

Thrown by the API client layer for backend communication failures.

```ts theme={null}
class APIError extends Error {
  name: 'APIError';
  code: APIErrorCode;
  statusCode?: number;                // HTTP status code, if available
  details?: Record<string, any>;     // Extra context from the API response
  message: string;
}
```

### APIErrorCode

```ts theme={null}
enum APIErrorCode {
  NETWORK_ERROR       = 'NETWORK_ERROR',        // No connection / DNS failure
  TIMEOUT             = 'TIMEOUT',              // Request exceeded 30s
  UNAUTHORIZED        = 'UNAUTHORIZED',          // 401
  BAD_REQUEST         = 'BAD_REQUEST',           // 400
  NOT_FOUND           = 'NOT_FOUND',             // 404
  SERVER_ERROR        = 'SERVER_ERROR',          // 5xx
  UNKNOWN_ERROR       = 'UNKNOWN_ERROR',         // Unexpected
  SDK_NOT_INITIALIZED = 'SDK_NOT_INITIALIZED',  // initialize() not called
}
```

### Type guard

```ts theme={null}
import { APIError, APIErrorCode } from '@taprails/tap-to-pay';

if (err instanceof APIError) {
  if (err.code === APIErrorCode.UNAUTHORIZED) {
    redirectToLogin();
  }
}
```

***

## APIErrorResponse

Raw error shape returned by the API:

```ts theme={null}
interface APIErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
  };
}
```