> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand validation and provider errors from the transcription API.

Errors return a JSON object with a stable `code` and a human-readable `message`.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "messages must be a JSON array"
  }
}
```

## Error codes

| HTTP status | Code                          | Cause                                             | Fix                                        |
| ----------- | ----------------------------- | ------------------------------------------------- | ------------------------------------------ |
| `400`       | `invalid_request`             | Invalid `messages`, `languages`, or `dictionary`. | Check JSON encoding and field types.       |
| `400`       | `missing_file`                | No `file` part in the multipart request.          | Include `file=@audio.mp3`.                 |
| `400`       | `too_many_files`              | More than one `file` part was uploaded.           | Send one audio file per request.           |
| `400`       | `unsupported_audio_type`      | File extension or MIME type is unsupported.       | Use `wav`, `webm`, `mp3`, `m4a`, or `ogg`. |
| `400`       | `unsupported_response_format` | Response format is not `json`.                    | Set `response_format=json` or omit it.     |
| `415`       | `unsupported_media_type`      | Request is not `multipart/form-data`.             | Use multipart form upload.                 |
| `502`       | `transcription_failed`        | ASR or LLM provider failed.                       | Retry or inspect provider logs.            |

## Debugging checklist

1. Confirm the API is reachable at `https://beta.api.voiceos.com`.
2. Confirm the request is `multipart/form-data`.
3. If sending `messages`, confirm it is a JSON string (not a nested form object).
4. Confirm `languages` is `"auto"`, one code, or a JSON array.
5. Confirm audio file type is supported.
6. Inspect `text` in successful responses and compare against the spoken input.

## Example invalid request

```bash theme={null}
curl https://beta.api.voiceos.com/v1/audio/transcriptions \
  -F "file=@sample.mp3" \
  -F "messages=not-json"
```

Response:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "messages must be valid JSON"
  }
}
```