---
title: "Errors"
description: "What the SDK throws, and what to do about it."
url: "https://docs.goomzo.africa/docs/developers/ts-sdk/errors"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Reference"
related:
  - /docs/developers/ts-sdk/lists
  - /docs/developers/ts-sdk/resources
---

> For an index of all documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt). Any page is also available as Markdown by adding .md to its URL.

# Errors

> What the SDK throws, and what to do about it.

The SDK throws one of three errors. The API's own codes are listed in [Errors](https://docs.goomzo.africa/docs/developers/errors?utm_source=llms&utm_medium=ai).

| Error                      | When                                                     |
| -------------------------- | -------------------------------------------------------- |
| `GoomzoError`              | The API answered with an error.                          |
| `GoomzoConnectionError`    | No answer came: the network failed, or it took too long. |
| `WebhookVerificationError` | A webhook's signature or timestamp didn't check out.     |

## Handle an error

```ts
import { GoomzoError } from '@goomzo/sdk'

try {
  await goomzo.messages.sendOne({ to: '0712345678', channel: 'sms', content: { text: 'Hi' } })
} catch (error) {
  if (error instanceof GoomzoError && error.code === 'invalid') {
    console.log(error.fields) // { "messages[0].to": { code: "invalid", message: "Add the country code…" } }
  }
  throw error
}
```

| Field       | Description                                                                            |
| ----------- | -------------------------------------------------------------------------------------- |
| `status`    | _Number._ The HTTP status, such as `400`.                                              |
| `code`      | _String._ What went wrong, such as `invalid`, `not_found` or `insufficient_sms`.       |
| `message`   | _String._ What the API said, in words.                                                 |
| `fields`    | _Object._ The fields that were wrong, by where they are, such as `customers[1].phone`. |
| `requestId` | _String._ The request's id. Include it when you contact Goomzo.                        |

`GoomzoConnectionError` has `timedOut`, `true` when the request took longer than the `timeout`.

## Retries

Network errors, `429` and `5xx` are tried again before anything is thrown, twice by default, waiting as long as
the API asks. Every `POST` carries the same `Idempotency-Key` on each try, so nothing is done twice.

## Next steps

- [Configuration](https://docs.goomzo.africa/docs/developers/ts-sdk/configuration?utm_source=llms&utm_medium=ai)
- [Errors in the API](https://docs.goomzo.africa/docs/developers/errors?utm_source=llms&utm_medium=ai)

---

For an index of all available documentation, see [/llms.txt](https://docs.goomzo.africa/llms.txt)