> This page is for Audio Decisions.

> 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

**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

```json wordWrap
{
  "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](#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

```json
{
  "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

<table>
  <thead>
    <tr>
      <th width="10%">
        Status
      </th>

      <th>
        Code
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        400
      </td>

      <td>
        `message_invalid`
      </td>

      <td>
        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](/audio-decisions/docs/limits#questions-and-context)

        .
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `question_invalid`
      </td>

      <td>
        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](/audio-decisions/docs/limits#questions-and-context)

        .
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `audio_decode_failed`
      </td>

      <td>
        The audio file could not be decoded.
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `audio_format_unsupported`
      </td>

      <td>
        The audio file is not MP3 or WAV.
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `audio_too_short`
      </td>

      <td>
        The audio is shorter than 5 seconds, or 

        `audio_duration_ms`

         is under 5000.
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `audio_too_long`
      </td>

      <td>
        The audio is longer than 5 minutes, or 

        `audio_duration_ms`

         is over 300000.
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `invalid_request`
      </td>

      <td>
        A query parameter has a value the endpoint does not accept, or 

        `cursor`

         is not one the endpoint issued. List runs only.
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        No code
      </td>

      <td>
        The request carried no valid API key. See 

        [Authentication](/audio-decisions/docs/authentication)

        .
      </td>
    </tr>

    <tr>
      <td>
        402
      </td>

      <td>
        `payment_required`
      </td>

      <td>
        The organization has no payment method on file, or has an unpaid invoice. An admin can update its payment method in the 

        [Hume Platform](https://cloud.hume.ai/)

        .
      </td>
    </tr>

    <tr>
      <td>
        403
      </td>

      <td>
        `forbidden`
      </td>

      <td>
        The credential does not grant access to this API, or the organization is not permitted to use it. Contact support to request access.
      </td>
    </tr>

    <tr>
      <td>
        404
      </td>

      <td>
        `not_found`
      </td>

      <td>
        No run with this ID exists in your organization. Get run only.
      </td>
    </tr>

    <tr>
      <td>
        404
      </td>

      <td>
        No code
      </td>

      <td>
        No endpoint exists at this path, or the endpoint does not accept this HTTP method.
      </td>
    </tr>

    <tr>
      <td>
        413
      </td>

      <td>
        `payload_too_large`
      </td>

      <td>
        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](/audio-decisions/docs/limits#which-limit-a-file-reaches-first)

        .
      </td>
    </tr>

    <tr>
      <td>
        415
      </td>

      <td>
        `unsupported_media_type`
      </td>

      <td>
        The request body is not 

        `multipart/form-data`

         for a decisions request, or not 

        `application/json`

         for an input tokens request.
      </td>
    </tr>

    <tr>
      <td>
        429
      </td>

      <td>
        No code
      </td>

      <td>
        The organization sent more than 60 requests in a minute. See 

        [Limits](/audio-decisions/docs/limits#rate-limits)

        .
      </td>
    </tr>

    <tr>
      <td>
        500
      </td>

      <td>
        `internal_error`
      </td>

      <td>
        The server failed while serving the request.
      </td>
    </tr>

    <tr>
      <td>
        503
      </td>

      <td>
        `server_busy`
      </td>

      <td>
        The service is at capacity.
      </td>
    </tr>
  </tbody>
</table>

## Handling errors

<table>
  <thead>
    <tr>
      <th width="30%">
        Status
      </th>

      <th>
        What to do
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        400, 413, 415 and 404 with no code
      </td>

      <td>
        Correct what 

        `code`

         and 

        `param`

         name, or the path or HTTP method, then resend. The same request fails again if sent unchanged.
      </td>
    </tr>

    <tr>
      <td>
        401, 402, 403
      </td>

      <td>
        Correct the credential or the organization's account: see 

        [Authentication](/audio-decisions/docs/authentication)

         for a 

        `401`

        , update the payment method for a 

        `402`

         and contact support for a 

        `403`

        . The request itself needs no change.
      </td>
    </tr>

    <tr>
      <td>
        404 with 

        `not_found`
      </td>

      <td>
        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](/audio-decisions/docs/runs#run-ids)

        .
      </td>
    </tr>

    <tr>
      <td>
        429, 503
      </td>

      <td>
        Wait the number of seconds in the 

        `Retry-After`

         header, then retry.
      </td>
    </tr>

    <tr>
      <td>
        500
      </td>

      <td>
        Retry. If it keeps failing, contact support with the 

        `request_id`

        .
      </td>
    </tr>
  </tbody>
</table>

## Reporting a problem

When [contacting support](/audio-decisions/docs/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`.