thymia Documentation

When a Helios model run completes with status COMPLETE_ERROR, the response includes two fields to help diagnose the issue:

Field	Description
`errorCode`	A machine-readable code identifying the category of error. Use this to handle errors programmatically.
`errorReason`	A human-readable description of the error. Intended for debugging, not for display to end users.

1 {
2   "id": "ddebd75b-99b3-42b4-ac65-5ce852c688e9",
3   "status": "COMPLETE_ERROR",
4   "errorCode": "ERR_RECORDING_TOO_SHORT",
5   "errorReason": "Recording supplied is too short. Please supply a recording containing at least 10 seconds of speech and that is under 3 minutes in length.",
6   "userLabel": "operator-1234"
7 }

Error codes

ERR_RECORDING_INVALID_FORMAT

The recording supplied was not in a supported file format.

Supported formats: FLAC, MP3, MP4, Ogg, WebM, WAV

Recommended action: Verify the file format and convert if necessary before submitting a new model run.

ERR_RECORDING_TOO_SHORT

The recording supplied contained less than the minimum required amount of speech.

Minimum speech duration: 10 seconds

Recommended action: Ask the user to speak for longer and submit a new model run.

ERR_RECORDING_TOO_LONG

The recording supplied exceeded the maximum allowed length.

Maximum recording length: 3 minutes

Recommended action: Trim the recording to under 3 minutes and submit a new model run.

ERR_TRANSCRIPTION_FAILED

No speech was detected in the recording supplied.

Recommended action: Check audio quality and ask the user to check their microphone before resubmitting.

ERR_INTERNAL

An internal error occurred during model processing.

Recommended action: Retry the model run. If the error persists, contact support@thymia.ai with the model run ID.

Warnings

1 {
2   "status": "COMPLETE_OK",
3   "warnings": [
4     "Audio quality may affect result accuracy."
5   ],
6   "results": { ... }
7 }

Results returned alongside warnings should be treated with caution. Consider flagging these to your users or discarding them depending on your use case.

HTTP errors

Status code	Meaning	Common cause
`401`	Unauthorized	Missing or invalid API key
`404`	Not found	Model run ID does not exist or data has been deleted
`422`	Unprocessable entity	Request body is malformed or missing required fields

A 404 response when retrieving results may indicate that data deletion was enabled for the model run and the 12-hour retention window has passed.

Next steps

Integration Guide — Build a complete production integration including error handling.
Interpreting Results — Understand what COMPLETE_OK results mean and how to use them.
API Reference — Complete endpoint documentation for the Helios API.