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, image upload, and run 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, image upload errors, and run errors.

Response format

{
  "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"
}

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.

HTTP codes

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 and video errors.

Message format

{
  "type": "error",
  "code": "rate_limited",
  "message": "audio ingest is outpacing the realtime limit; frame dropped",
  "retryable": true
}

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 explains how to pair each reply with the frame it answers.

Shared codes

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 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 lists the code for each reason.

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.

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