Errors
Handle Voice Developer API authentication, subscription, validation, and lookup failures.
| Status | Cause | Fix |
|---|
401 | Missing, malformed, expired, revoked, or invalid API key | Send Authorization: Bearer ntfy_your_api_key with a valid key |
401 | Key is valid but not usable for API-key authentication | Create a customer API key in the Portal |
403 | API key does not include Voice access | Create or rotate a key with the VOICE service grant |
| Status | Cause | Fix |
|---|
403 | The API-key customer does not have an active Voice subscription | Activate Voice for the customer account before calling the Developer API |
| Status | Cause | Fix |
|---|
400 | customerNumber is missing or not E.164 | Send a number such as +255700000001 |
400 | callSessionId is empty or longer than 128 characters | Send the local session row ID or backend call attempt ID returned by the API |
| Status | Cause | Fix |
|---|
404 | No owned call matches the supplied callSessionId | Check that the ID belongs to the API-key customer and has not been deleted |
Voice calls depend on the configured Voice provider and internal queues. Provider failures, queue failures, or account-level Voice configuration issues can surface as server errors. Retry only when the operation is safe for your workflow, because starting a call is not idempotent.
