---
title: "Error handling"
description: "The errors the SDK throws while verifying, and the HTTP response each one deserves."
source: "/docs/errors"
updated: "2026-09-24"
---

# Error handling

The errors the SDK throws while verifying, and the HTTP response each one deserves.

## Error classes

For callback/signature verification errors, the HTTP column suggests a response from your callback handler. For `ReferenceListError`, `upstream` means the API's HTTP status exposed as `.status`; your server decides what to return to its own caller.

| Error Class                    | Thrown by                                      | HTTP     | Cause                                                                                                                                    |
| ------------------------------ | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `InvalidSignatureError`        | `verifyCallback`                               | 401      | Callback HMAC does not match - possible tampering or wrong secret.                                                                       |
| `NonceMismatchError`           | `verifyCallback`                               | 401      | Nonce in callback does not match the session nonce.                                                                                      |
| `ExpiredTimestampError`        | `verifyCallback`                               | 401      | Callback timestamp is outside the accepted time window.                                                                                  |
| `MalformedCallbackError`       | `verifyCallback`                               | 400      | Required callback fields are missing or unparseable.                                                                                     |
| `InvalidAuthUrlSignatureError` | `verifyAuthUrlSignature`                       | 401      | Auth URL `sig` is missing or does not match - the URL was rewritten.                                                                     |
| `ReferenceListError`           | `addToReferenceList / removeFromReferenceList` | upstream | API request returned a non-2xx status. Inspect `.status` and `.code`; see [endpoint HTTP statuses](/docs/api.md#endpoint-http-statuses). |

## Error codes

Every class extends `VoiceAuthError` and carries `.code`. Verification codes are `INVALID_SIGNATURE`, `NONCE_MISMATCH`, `EXPIRED_TIMESTAMP`, `MALFORMED_CALLBACK`, and `INVALID_AUTH_URL_SIGNATURE`. `ReferenceListError.code` preserves the API's error code, with `REFERENCE_LIST_REQUEST_FAILED` as the fallback when the error body has no usable code. Transport failures and successful-response JSON parsing failures are native errors.


## Sitemap

See the full [sitemap](https://helix.id/sitemap.md) for all pages.