> This page is for Expression Measurement. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://dev.hume.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server. # Errors **The upload and run endpoints return errors as HTTP responses, and realtime sessions send them as `error` messages.** Both include a stable `code` to handle in your application and a `message` for logs and debugging. Some codes, such as `config_invalid`, `message_invalid`, and `internal_error`, appear in both with the same meaning. ## HTTP errors The [audio upload](/expression-measurement/docs/audio/upload), [image upload](/expression-measurement/docs/video/upload), and [run](/expression-measurement/docs/runs) endpoints return an error as a JSON body with a `4xx` or `5xx` status. The status says how the request failed, and `code` says why. Each of these endpoints also documents its errors in its own guide: [audio upload errors](/expression-measurement/docs/audio/upload#errors), [image upload errors](/expression-measurement/docs/video/upload#errors), and [run errors](/expression-measurement/docs/runs#errors). ### Response format #### 400 Bad Request ```json { "type": "error", "code": "config_invalid", "message": "the config part is not valid: unknown field `timer_ms`, expected `measurement_timer_ms` at line 1 column 11", "request_id": "3f9a1c07e2b84d56a0c7e19b5d2f8a64" } ``` **`type`** Always `error`. --- **`code`** A stable string to branch on. See [HTTP codes](#http-codes). --- **`message`** A description for logs and debugging. The wording may change without notice. --- **`request_id`** Identifies the request in Hume's records. Quote it when contacting support. --- A `401` is answered before the request reaches the service, so its body has no `type` or `code`. It carries only a `message`, and a `request_id` when an API key was rejected. See [Authentication](/expression-measurement/docs/authentication). ### HTTP codes
Status Code Endpoints Description
400 `message_invalid` Upload The multipart body could not be read, is missing its `file` part, or carries a part with another name. Audio upload takes exactly one `file` part; image upload takes one or more.
400 `config_invalid` Upload The `config` part is not valid JSON, names an unrecognized field, holds a value outside its range, or appears more than once.
400 `audio_decode_failed` Audio upload The audio could not be decoded: a WAV file that is truncated or malformed, is at another sample rate, channel count, or sample format, or uses the extensible WAV header, or a file that is empty or is not a whole number of 16-bit samples.
400 `image_decode_failed` Image upload An image could not be decoded.
400 `invalid_request` Runs A query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued.
401 None All The request carried no valid API key or access token. See [Authentication](/expression-measurement/docs/authentication) .
403 `forbidden` Upload Your organization is not permitted to use this endpoint. Contact support.
404 `not_found` All No run with this ID exists in your organization, or no endpoint exists at this path.
405 `method_not_allowed` All The endpoint does not accept this HTTP method. The `Allow` header lists the methods it does accept.
413 `audio_too_long` Audio upload The request body is over the size limit.
413 `image_too_large` Image upload The request body or one image is over the size limit, or an image has more pixels than the endpoint accepts.
415 `unsupported_media_type` Upload The audio is in a format the server recognizes but does not accept, such as MP3 or FLAC, or an image is not a JPEG.
500 `internal_error` All The server failed while serving the request.
503 `server_busy` All The service is too busy to serve the request now.
### Retrying 1. **A request that failed with a `4xx` status fails again if sent unchanged.** Correct what `code` names first. A `403` is not caused by the request, so contact support instead. 2. **After a `500`, retry the request.** If it keeps failing, contact Hume with the `request_id`. 3. **After a `503`, wait before retrying.** The response carries a `Retry-After` header giving the number of seconds to wait. ## Realtime errors A realtime session reports a problem as an `error` message. After a recoverable error, the session continues. After an unrecoverable error, it sends `session.closed` and closes the connection. Codes that only one endpoint sends are documented in that endpoint's guide: [audio errors](/expression-measurement/docs/audio/realtime#errors) and [video errors](/expression-measurement/docs/video/realtime#errors). ### Message format #### error ```json { "type": "error", "code": "rate_limited", "message": "audio ingest is outpacing the realtime limit; frame dropped", "retryable": true } ``` **`type`** Always `error`. --- **`code`** A stable string to branch on. --- **`message`** A description for logs and debugging. The wording may change without notice. --- **`retryable`** `false` for every error that ends the session, and `true` for every error the session survives. The exception is `internal_error` on the video endpoint, where it says whether the failure was temporary and the frame is worth resending. --- On the audio endpoint, the server replies only to a rejected frame, with an `error`. On the video endpoint, it replies to every frame, and [Matching results to frames](/expression-measurement/docs/video/realtime#matching-results-to-frames) explains how to pair each reply with the frame it answers. ### Shared codes
Code Session Description
`message_invalid` Continues A text message was not valid JSON, had no `type` field, or had a `type` the endpoint does not recognize. Media must be sent as binary frames, not as text.
`rate_limited` Continues Media arrived faster than the endpoint allows, and the frame was not processed. Slow down, and resend the frame if the stream must be continuous.
`config_invalid` Ends A `session.update` contained an unrecognized field or an unsupported value, or arrived after the configuration locked at the first media frame. See [Configuration](/expression-measurement/docs/sessions#configuration) .
`message_too_large` Ends A WebSocket message exceeded the endpoint's size limit: 1 MiB on the audio endpoint, 2 MB on the video endpoint. Send smaller messages.
`internal_error` Varies Processing failed unexpectedly. On the audio endpoint the session ends. On the video endpoint the frame is skipped and the session continues, until five consecutive frames fail.
When an error ends the session, the `error` is followed by `session.closed` with `reason` set to `error`, and the connection closes with code 1008. Open a new connection to start another session. The problems a session reports, such as rejected frames and failed measurements, are also recorded in its event log. [Getting events](/expression-measurement/docs/runs#getting-events) describes the endpoint that returns the log and every kind of event in it. ### Close codes When the server ends a session, it closes the WebSocket with one of these codes. The code shows whether `session.closed` was sent first. Close frames carry a code and no reason text, so the reason is in `session.closed`. [Closing](/expression-measurement/docs/sessions#closing) lists the code for each reason.
Close code Preceded by Description
1000 `session.closed` with `reason` set to `client_request` or `idle_timeout` The session ended normally: the client sent `session.close` , or the session was idle.
1008 `error` , then `session.closed` with `reason` set to `error` An error ended the session. Open a new connection to start another session.
1011 Nothing The server could not continue the session. Open a new connection to start another session. See [Connection failures](#connection-failures) .
1012 `session.closed` with `reason` set to `server_shutdown` The server is restarting. Open a new connection right away to start another session.
### Handshake failures A handshake with a missing or invalid credential is rejected with `401 Unauthorized`, and a handshake from an organization that is not permitted to use the endpoint is rejected with `403 Forbidden`. Both are rejected before a WebSocket exists, so no `error` message can be sent; read the status from your client library's handshake result. See [Authentication](/expression-measurement/docs/authentication). ### Connection failures If the server cannot continue a session, it closes the connection with code 1011 without sending `session.closed`. Treat a close that was not preceded by `session.closed` as a lost session and open a new connection. 1. **If the connection drops without a close frame, the session has ended.** Client libraries report this as close code 1006. Open a new connection. 2. **A text message that is not valid UTF-8 ends the session with 1011.** ## Reporting a problem When contacting Hume, include the identifier of the request or session: 1. **For an upload or run request**, the `request_id` from the response or the error body. 2. **For a realtime session**, the `session_id` from `session.created`. ## Next steps #### [Limits](/expression-measurement/docs/limits) The limits of every endpoint, and what happens when a request exceeds one. #### [Runs](/expression-measurement/docs/runs) The problems each request and session reported, after the fact.