Errors

Node.js SDK - Error handling and exception classes

Error Hierarchy

All SDK errors extend DocuTrayError:

DocuTrayError (base)
├── APIConnectionError (network errors)
│   └── APITimeoutError (request timeout)
└── APIError (HTTP errors)
    ├── BadRequestError (400)
    ├── AuthenticationError (401)
    ├── PermissionDeniedError (403)
    ├── NotFoundError (404)
    ├── ConflictError (409)
    ├── UnprocessableEntityError (422)
    ├── RateLimitError (429)
    └── InternalServerError (5xx)

Usage

import DocuTray, {
  DocuTrayError,
  APIError,
  AuthenticationError,
  RateLimitError,
} from 'docutray';

const client = new DocuTray();

try {
  await client.convert.run({ documentTypeCode: 'invoice', url: '...' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof APIError) {
    console.log(error.statusCode, error.message, error.requestId);
  } else if (error instanceof DocuTrayError) {
    console.log('SDK error:', error.message);
  }
}

DocuTrayError

Base class for all SDK errors.

PropertyTypeDescription
messagestringError description
namestringError class name

APIConnectionError

Thrown when the SDK cannot establish a connection to the API.

PropertyTypeDescription
causeunknownThe underlying connection error

APITimeoutError

Thrown when a request exceeds the configured timeout. Extends APIConnectionError.

APIError

Thrown when the API returns a non-success HTTP status code.

PropertyTypeDescription
statusCodenumberHTTP status code
requestIdstring | undefinedThe x-request-id header
bodyunknownParsed response body
headersHeadersRaw response headers

Status-Specific Errors

Error ClassStatus CodeDescription
BadRequestError400Invalid request parameters
AuthenticationError401Invalid or missing API key
PermissionDeniedError403Insufficient permissions
NotFoundError404Resource not found
ConflictError409Resource conflict
UnprocessableEntityError422Validation errors
RateLimitError429Rate limit exceeded
InternalServerError5xxServer error

RateLimitError

Includes rate-limit metadata from response headers.

PropertyTypeDescription
retryAfternumber | undefinedSeconds to wait before retrying
limitTypestring | undefinedType of rate limit hit
limitnumber | undefinedMax requests in current window
remainingnumber | undefinedRequests remaining in window
resetTimeDate | undefinedWhen the rate limit resets

On this page