API errors and troubleshooting
Diagnose authentication, credit, validation, and asynchronous job failures.
Errors use a JSON envelope rather than a successful media response:
details and request_id are included when available. Save the response's X-Request-Id for support.
| HTTP status | Common cause | Next step |
|---|---|---|
| 400 | Invalid JSON fields, model, input, or settings | Inspect the message and details; check the model catalog |
| 401 | Missing, invalid, expired, or revoked key | Verify Bearer authentication and the current key |
| 402 | Insufficient credits or member credit cap | Read /credits; review Billing and member limits |
| 403 | Missing scope, ineligible API access, or removed membership | Check the key's scopes, workspace, and purchase/subscription status |
| 404 | Resource unavailable in this workspace | Confirm the resource ID and the workspace associated with the key |
| 409 | Operation already processing or an invalid state transition | Wait, retrieve the resource, or inspect its current state |
| 422 | Idempotency key reused with a different request | Restore the original body for a retry or use a new key for a new operation |
| 429 | Workspace request limit | Respect Retry-After and back off |
| 502 / 503 | Upstream failure or unavailable worker/service | Preserve IDs, inspect job state, and retry carefully |
No media in a successful response
A 202 response means queued. Poll the specific generation or speech resource for completion. A batch can partially succeed; inspect both outputs and errors.
An output link stopped working
A signed output URL expires. Retrieve the resource again for a fresh URL and honor expires_at. A storage upload URL is not a playback URL.
A voice cannot be selected
Preset voice IDs are model-specific. Retrieve /voices/catalog for the selected speech model. Custom resource IDs work with Speech Cloning, not the Speech Lite preset catalog.
A request timed out
Do not immediately create a second operation. Retry using the original idempotency key and identical body, or retrieve the resource if you received its ID. Use a new key only for an intentional new operation.
Ask for help
Send the endpoint, HTTP status, request ID, approximate time, and a sanitized error message to support@verbatik.com. Remove credentials, webhook secrets, and confidential prompt or media data.