Skip to main content
Errors return a JSON object with a stable code and a human-readable message. 
{
  "error": {
    "code": "invalid_request",
    "message": "messages must be a JSON array"
  }
}

​
Error codes

HTTP statusCodeCauseFix
400invalid_requestInvalid messages, languages, or dictionary.Check JSON encoding and field types.
400missing_fileNo file part in the multipart request.Include file=@audio.mp3.
400too_many_filesMore than one file part was uploaded.Send one audio file per request.
400unsupported_audio_typeFile extension or MIME type is unsupported.Use wav, webm, mp3, m4a, or ogg.
400unsupported_response_formatResponse format is not json.Set response_format=json or omit it.
415unsupported_media_typeRequest is not multipart/form-data.Use multipart form upload.
502transcription_failedASR 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

curl https://beta.api.voiceos.com/v1/audio/transcriptions \
  -F "file=@sample.mp3" \
  -F "messages=not-json"
Response: 
{
  "error": {
    "code": "invalid_request",
    "message": "messages must be valid JSON"
  }
}