Error handling

Handle API errors, configure retries, and understand error types in the UQPAY Node.js SDK.

Error types

All API errors throw typed error classes that extend UQPayError:

import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  NetworkError,
  SimulatorNotAvailableError,
} from '@uqpay/sdk'

Each error exposes the following fields:

Field	Type	Description
message	string	Human-readable error message
httpStatus	number	HTTP status code
type	string	API error type string
code	string	API error code

Catch errors

try {
  const account = await client.account.accounts.retrieve('acc-123')
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Account not found')
  } else if (err instanceof ValidationError) {
    console.log('Bad request:', err.message)
  } else if (err instanceof RateLimitError) {
    console.log('Rate limited, will retry automatically')
  } else if (err instanceof NetworkError) {
    console.log('Network error:', err.message)
  } else if (err instanceof SimulatorNotAvailableError) {
    console.log('Simulator is only available in sandbox')
  }
}

Retries

The SDK automatically retries failed requests on server errors, rate limits, and network errors using exponential backoff.

Configure retries globally or per request:

// Global — set when creating the client
const client = new UQPayClient({
  // ...
  maxRetries: 3,
})

// Per request — overrides the global setting
await client.account.accounts.retrieve('acc-123', { maxRetries: 0 })