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. |
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.