Node.js SDK errors, retries, and timeouts - Telnyx

Handling errors

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of APIError will be thrown:

const numberOrder = await client.numberOrders
  .create({ phone_numbers: [{ phone_number: '+15558675309' }] })
  .catch(async (err) => {
    if (err instanceof Telnyx.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

Error codes are as follows:

Status Code	Error Type
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors will all be retried by default. You can use the maxRetries option to configure or disable this:

// Configure the default for all requests:
const client = new Telnyx({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.numberOrders.create({ phone_numbers: [{ phone_number: '+15558675309' }] }, {
  maxRetries: 5,
});

Timeouts

Requests time out after 1 minute by default. You can configure this with a timeout option:

// Configure the default for all requests:
const client = new Telnyx({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.numberOrders.create({ phone_numbers: [{ phone_number: '+15558675309' }] }, {
  timeout: 5 * 1000,
});

On timeout, an APIConnectionTimeoutError is thrown. Note that requests which time out will be retried twice by default.

⌘I