Error Handling

The SDK provides typed error classes for every failure scenario.

Error classes


import {
  EInvoiceError,
  EInvoiceApiError,
  EInvoiceRateLimitError,
  EInvoiceTimeoutError,
  EInvoiceConfigError,
  EInvoiceWebhookError,
} from '@useyona/einvoice-js';

Class	Thrown when
`EInvoiceError`	Base class for all SDK errors
`EInvoiceApiError`	HTTP 4xx/5xx response from the API
`EInvoiceRateLimitError`	HTTP 429 — too many requests
`EInvoiceTimeoutError`	Request exceeds configured timeout
`EInvoiceConfigError`	SDK misconfiguration (e.g. missing `organizationId`)
`EInvoiceWebhookError`	Webhook signature verification failed

EInvoiceApiError

Thrown for any HTTP 4xx or 5xx response.

Property	Type	Description
`statusCode`	`number`	HTTP status code
`errorCode`	`string`	Machine code (e.g. `'VAL001'`)
`message`	`string`	Human-readable message
`errors`	`Array<{ field?: string; message: string }>`	Field-level errors


try {
  await client.invoices.create({ /* ... */ });
} catch (err) {
  if (err instanceof EInvoiceApiError) {
    handleValidationError(err.statusCode, err.errorCode, err.errors);
  }
}

ℹ Available properties on EInvoiceApiError

err.statusCode — the HTTP status (e.g. 400). err.errorCode — a machine-readable code (e.g. 'VAL001'). err.errors — an array of field-level errors with field and message.

EInvoiceRateLimitError

Thrown when the API returns HTTP 429. Extends EInvoiceApiError.

Property	Type	Description
`retryAfter`	`number`	Seconds to wait before retrying


if (err instanceof EInvoiceRateLimitError) {
  console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  await sleep(err.retryAfter * 1000);
  // retry the request
}

EInvoiceTimeoutError

Thrown when a request exceeds the configured timeout.


if (err instanceof EInvoiceTimeoutError) {
  logTimeout(err.timeoutMs);
}

ℹ timeoutMs

err.timeoutMs contains the timeout value (in milliseconds) that was exceeded.

EInvoiceConfigError

Thrown for SDK misconfiguration — e.g. calling client.webhooks.create() without organizationId.

EInvoiceWebhookError

Thrown when webhook signature verification fails in verifyWebhook().

Automatic retries

The SDK automatically retries certain errors:

Error type	Retried?	Behavior
5xx errors	Yes	Up to `maxAttempts` with exponential backoff + jitter
429 errors	Yes	Respects `Retry-After` header, then retries
4xx errors	Never	These are client errors — fix the request

Error codes reference

Code	Meaning	HTTP Status
AUTH001	Invalid credentials	401
AUTH002	Token expired	401
AUTH004	Unauthorized	401
AUTH005	Forbidden	403
VAL001	Validation failed	400
VAL002	Missing required field	400
RES001	Not found	404
RES002	Already exists	409
BIZ001	Insufficient balance	400
BIZ004	Invalid state	400
INV001	Invalid invoice format	400
INV002	Already submitted	400
INV003	Cannot modify	400
SYS001	Internal error	500
TAX001	Tax authority connection error	502