# 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](https://docs.helix.id/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.