Errors & troubleshooting
REST errors normally use an envelope containing an error object with a safe code, message, and type. Do not rely on message text as a stable machine identifier.
HTTP responses
| Status | Meaning | What to check |
|---|---|---|
400 | Invalid request combination | Workspace selector and parameter formats |
401 | Authentication failed | Missing, invalid, or revoked API key |
403 | Permission denied | Required scopes and current workspace access |
404 | Record unavailable in this workspace | Correct ID, workspace, and version |
409 | State conflict | Current resource state before retrying |
422 | Validation failed | Required fields, supported values, and body shape |
429 | A limit or rate restriction | Returned error code and workspace limits |
503 | Service or configuration unavailable | Provider setup and retry with backoff where appropriate |
Do not blindly retry mutations such as key creation or conversation creation: the first request may have succeeded even if its response was lost. Refresh the relevant resource list or inspect its status first.
WebSocket failures
| Code | Likely cause |
|---|---|
4400 | Invalid initial handshake, unsupported audio format, or protocol version |
4401 | Invalid, consumed, or expired stream token |
4403 | Required provider access or authorization unavailable |
4404 | Conversation/version unavailable |
4008 | Workspace call limit reached |
1013 | Runtime unavailable or unsupported engine path |
A rejected handshake may appear as an HTTP error in a WebSocket library rather than exposing a close code. Never print the connection URL with its stream token into error logs.
No audio or delayed audio
Verify 16 kHz mono PCM16 input, real-time pacing, and version-1 output decoding. Make sure send and receive loops run concurrently. Do not buffer the entire assistant response before starting playback.
If interruptions leave old audio playing, clear the interrupted generation’s playback queue. If speech is cut off at the end, wait for audio exhaustion and queue drain; a completed transcript is not the end of audio.
Analysis unavailable
Call completion, persisted conversation material, recording, and analysis have distinct states. Read the result’s processing status before treating a missing analysis as a permanent failure.
When contacting the EVA team, include the workspace ID, conversation ID, approximate time, and sanitized error code. Exclude permanent keys, stream tokens, and provider secrets.