Errors | Hume API

Every Audio Decisions endpoint returns errors as a JSON body with a 4xx or 5xx status. The status says how the request failed, and code says why. Branch on code in your application, and use message for logs and debugging.

Response format

400 Bad Request

{
  "type": "error",
  "code": "question_invalid",
  "message": "score criteria must define at least 2 levels",
  "param": "/questions/clarity/criteria",
  "request_id": "req_01JB8XA3C5RD"
}

type

Always error.

code

A stable string to branch on. See Codes.

message

A description for logs and debugging. The wording may change without notice.

param

Where the error was found: a JSON Pointer into the request part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Absent when the error has no narrower location than the whole request.

request_id

Identifies the request in Hume’s records. Quote it when contacting support.

Gateway errors

Hume’s API gateway answers three errors before the request reaches the service: a 401 for a missing or invalid credential, a 429 for a rate limit and a 404 for a path or HTTP method the API does not serve. Their body has a message but no type or code, so branch on the status for these.

429 Too Many Requests

{
  "message": "API rate limit exceeded"
}

Of these, a 404 always carries a request_id, a 401 carries one only when an API key was rejected, and a 429 never does.

Codes

Status	Code	Description
400	`message_invalid`	The request body is malformed or does not match the schema outside a question. Examples are a decisions request with no `request` part or with no `file` part or more than one, an input tokens request with no `audio_duration_ms` and a request with more questions than the limits allow, a question ID longer than 256 characters or a `context` longer than 1,000 characters. See Limits.
400	`question_invalid`	A question is invalid, including when it does not match the schema, for example because it has duplicate option names, fewer than two options or `instructions` longer than 500 characters. See Limits.
400	`audio_decode_failed`	The audio file could not be decoded.
400	`audio_format_unsupported`	The audio file is not MP3 or WAV.
400	`audio_too_short`	The audio is shorter than 5 seconds, or `audio_duration_ms` is under 5000.
400	`audio_too_long`	The audio is longer than 5 minutes, or `audio_duration_ms` is over 300000.
400	`invalid_request`	A query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only.
401	No code	The request carried no valid API key. See Authentication.
402	`payment_required`	The organization has no payment method on file, or has an unpaid invoice. An admin can update its payment method in the Hume Platform.
403	`forbidden`	The credential does not grant access to this API, or the organization is not permitted to use it. Contact support to request access.
404	`not_found`	No run with this ID exists in your organization. Get run only.
404	No code	No endpoint exists at this path, or the endpoint does not accept this HTTP method.
413	`payload_too_large`	The request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together. See which limit a file reaches first.
415	`unsupported_media_type`	The request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request.
429	No code	The organization sent more than 60 requests in a minute. See Limits.
500	`internal_error`	The server failed while serving the request.
503	`server_busy`	The service is at capacity.

Handling errors

Status	What to do
400, 413, 415 and 404 with no code	Correct what `code` and `param` name, or the path or HTTP method, then resend. The same request fails again if sent unchanged.
401, 402, 403	Correct the credential or the organization’s account: see Authentication for a `401`, update the payment method for a `402` and contact support for a `403`. The request itself needs no change.
404 with `not_found`	If the `run_id` came from a decisions response moments ago, wait a few seconds and retry, since a run can take a moment to appear. If it still returns `404`, the run was not recorded or the ID is wrong. See Runs.
429, 503	Wait the number of seconds in the `Retry-After` header, then retry.
500	Retry. If it keeps failing, contact support with the `request_id`.

Reporting a problem

When contacting support, include the request ID. Every response from the service, including a success, carries it in the X-Request-Id header, and every error body from the service carries it as request_id.