Errors

Error hierarchy for error handling in the DocuTray Node.js SDK

Error Hierarchy

All errors thrown by the SDK extend DocuTrayError. API errors include HTTP status code information and response details.

DocuTrayError
├── APIConnectionError
│   └── APITimeoutError
└── APIError
    ├── 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 (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof APIError) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
    console.log('Request ID:', err.requestId);
  } else if (err instanceof DocuTrayError) {
    console.log('SDK error:', err.message);
  }
}

DocuTrayError

Base error class for all SDK errors.

PropertyTypeDescription
messagestringError message
namestringError class name

APIConnectionError

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

PropertyTypeDescription
causeunknownThe underlying error that caused the connection failure

APITimeoutError

Thrown when a request exceeds the configured timeout or is aborted. Extends APIConnectionError.

APIError

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

PropertyTypeDescription
statusCodenumberThe HTTP status code
requestIdstring | undefinedThe x-request-id header value
bodyunknownThe parsed response body
headersHeadersThe raw response headers

Status-Specific Errors

Error ClassHTTP StatusDescription
BadRequestError400Invalid request parameters
AuthenticationError401Invalid or missing API key
PermissionDeniedError403Insufficient permissions
NotFoundError404Resource not found
ConflictError409Resource conflict
UnprocessableEntityError422Validation errors
RateLimitError429Rate limit exceeded
InternalServerError5xxServer-side errors

RateLimitError

Includes additional rate-limit metadata extracted from response headers.

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

On this page