Error Handling

An API request can fail when your code is valid. The user can be signed out. An ID can be incorrect. The server can have an error. The SDK throws an error for these failures. Put applicable calls that use await in a try/catch block.

There are two broad kinds of failure:

PackbaseError means that Packbase received the request and sent an error status.
A native error such as TypeError usually means that the request did not receive an HTTP response. For example, the device can be offline or DNS can fail.

Catch a failed request

try {
  const  = await .('a-pack-id')
  .(.)
} catch () {
  if ( instanceof ) {
    .(`Packbase returned ${.}: ${.}`)
  } else {
    .('Could not reach Packbase', )
  }
}

JavaScript can throw a value of any type. Thus, TypeScript initially gives a caught value the unknown type. The instanceof PackbaseError check changes it to the SDK error class. You can then use properties such as status.

`PackbaseError` properties

Property	Description
`status`	The HTTP status number, such as `401`, `404`, or `500`.
`summary`	A readable explanation returned by Packbase.
`code`	An optional machine-readable code for a more specific case.
`raw`	The full parsed error response. Use it for fault isolation.
`message`	The standard JavaScript `Error` message; it matches `summary`.

These properties identify frequently used HTTP status codes:

Property	Status	Usual meaning
`isUnauthorized`	`401`	The user is not signed in, or the key is invalid.
`isForbidden`	`403`	The user does not have permission.
`isNotFound`	`404`	The requested item does not exist.
`isConflict`	`409`	The request conflicts with the current state.
`isServerError`	`500` or higher	The server has an error.

This example gives the user a message for each error type:

try {
  const  = await .('a-pack-id')
  .(.)
} catch () {
  if (!( instanceof )) {
    .('Check your internet connection and try again.')
  } else if (.) {
    .('That pack could not be found.')
  } else if (.) {
    .('Please sign in and try again.')
  } else if (.) {
    .('You are signed in, but you do not have access to that pack.')
  } else {
    .(`Packbase error: ${.}`)
  }
}

Check a specific error code

Two failures can have the same HTTP status. The optional code property gives a more specific cause when the server supplies one.

try {
  await .('a-pack-id').()
} catch () {
  if ( instanceof  && . === 'INVITE_REQUIRED') {
    .('This pack is invite-only.')
  } else if ( instanceof  && .) {
    .('You may already be a member of this pack.')
  } else {
    throw 
  }
}

The final throw error passes unexpected failures to the surrounding error handler. Do not ignore these errors. Ignored errors make subsequent fault isolation difficult.

Timeouts while creating a howl

The server creates howls in a background job. If the wait time is more than the configured timeout, the SDK throws a PackbaseError with status 408:

try {
  const  = await ..(
    { : 'pack-id', : 'Hello', : ['rating_safe'] },
    { : 60_000 },
  )
} catch () {
  if ( instanceof  && . === 408) {
    .('The howl is still processing. Try again in a moment.')
  } else {
    throw 
  }
}

This timeout means that the SDK stopped the wait. The server can continue the job.

Cancel a request

All SDK requests accept an AbortSignal. Howl creation carries the same signal through the initial request, polling delays, status checks, and final fetch.

const  = new ()
const  = ..({ : . })
.()

try {
  await 
} catch () {
  if ( instanceof  && . === 'AbortError') {
    .('Request cancelled')
  }
}

Network failures

The SDK does not wrap low-level errors that fetch throws. In most runtimes, these failures are TypeError values:

try {
  await ..()
} catch () {
  if ( instanceof ) {
    .('Packbase rejected the request:', .)
  } else if ( instanceof ) {
    .('Network request failed:', .)
  } else {
    throw 
  }
}

A testing helper

PackbaseError.fromResponse() creates an error from a status and response body:

const  = .(422, {
  : 'Validation failed',
  : 'INVALID_SLUG',
})

The SDK uses this method internally. Most applications do not call it directly. Use it in a unit test to simulate an API failure.