---
title: "Errors"
description: "What the SDK throws, and what to do about it."
url: "https://docs.goomzo.africa/docs/developers/php-sdk/errors"
docs_index: /llms.txt
lastUpdated: 2026-11-12
section: "Reference"
related:
  - /docs/developers/php-sdk/lists
  - /docs/developers/php-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 exceptions, all implementing `Goomzo\Exception\GoomzoException`. The API's own codes are
listed in [Errors](https://docs.goomzo.africa/docs/developers/errors?utm_source=llms&utm_medium=ai).

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

## Handle an error

```php
use Goomzo\Exception\ApiException;

try {
    $goomzo->messages->sendOne(['to' => '0712345678', 'channel' => 'sms', 'content' => ['text' => 'Hi']]);
} catch (ApiException $error) {
    if ($error->errorCode === 'invalid') {
        print_r($error->fields); // ['messages[0].to' => ['code' => 'invalid', 'message' => 'Add the country code…']]
    }
    throw $error;
}
```

| Property       | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `status`       | _int._ The HTTP status, such as `400`.                                                |
| `errorCode`    | _string._ What went wrong, such as `invalid`, `not_found` or `insufficient_sms`.      |
| `getMessage()` | _string._ What the API said, in words.                                                |
| `fields`       | _array._ 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.                       |

`ConnectionException` 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/php-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)