Skip to main content

​
Errors & Troubleshooting

​
Authentication Errors

HTTPCodeDescription
401AUTH_MISSING_TOKENAuthorization token is missing
401AUTH_INVALID_TOKENToken is invalid or expired
403AUTH_UNAUTHORIZEDInsufficient permissions

​
Validation Errors

HTTPCodeDescription
400VALIDATION_ERRORInput data validation failed
400INVALID_FILE_FORMATUnsupported file format
400FILE_TOO_LARGEFile exceeds maximum size (50 MB)
400INVALID_PHONE_NUMBERInvalid phone number format
400AUDIO_FILENAME_MISMATCHFile name doesn’t match audio_file_name in metadata
404FILE_NOT_FOUNDFile not found in S3 after upload

​
Error Response Format

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Missing required field.",
  "details": {
    "field": "metadata_filename",
    "error": "Field required"
  }
}

​
Metadata Errors

ErrorDescriptionSolution
METADATA_EMPTYCSV file is emptyCheck your CSV file has content
MISSING_COLUMNSRequired columns missingEnsure all required columns are present
EMPTY_CELLRequired field is emptyFill in all required fields
INVALID_DATETIMEInvalid date formatUse ISO 8601 or Unix timestamp
INVALID_ANONYMIZED_TEXTInvalid transcript formatCheck role tags (see Transcription Format)
INVALID_ARCHIVE_FORMATInvalid archive formatUse .zip format only

​
API Key Errors

HTTPDescription
401Key not provided or invalid format
403Key is inactive, deleted, or belongs to wrong firm

​
Common Issues & Solutions

​
401 Unauthorized on API requests

Cause: Missing or invalid token. Solution:
  • Verify the Authorization: Bearer <token> header is present
  • Check that your token hasn’t expired
  • Request a new token from your administrator

​
400 INVALID_FILE_FORMAT (audio)

Cause: Unsupported audio file extension. Solution: Use one of the supported formats: .wav, .mp3, .flac, .ogg, .aiff, .au

​
400 FILE_TOO_LARGE

Cause: File exceeds 50 MB. Solution:
  • Compress the audio file
  • Use batch upload for large volumes

​
400 AUDIO_FILENAME_MISMATCH

Cause: The uploaded file name doesn’t match the metadata. Solution:
  • Single upload: Ensure metadata.audio_file_name exactly matches the uploaded file name
  • Batch upload: Ensure audio_file_name in CSV exactly matches the file name in the ZIP

​
403 Forbidden on Step 2 (S3 upload)

Cause: Presigned URL has expired (valid for 1 hour only). Solution: Go back to Step 1 and request new presigned URLs.

​
404 File Not Found on Step 3

Cause: File wasn’t uploaded to S3 or S3 is still processing. Solution:
  • Verify Step 2 returned 200 or 204
  • Add a 2–3 second delay between Step 2 and Step 3

​
MISSING_COLUMNS in CSV

Cause: Required CSV columns are missing. Solution: Check required columns for your upload type:
  • audio_file_name
  • client_phone_number
  • operator_name
  • start_time
  • segment_type
  • right_channel
  • left_channel

​
INVALID_ANONYMIZED_TEXT

Cause: Transcript text has invalid role tags. Solution:
  • Use supported tags: <operator>, <client> (and localized variants)
  • Ensure there is text between every pair of tags
  • Format: <operator>text<client>text

​
INVALID_PHONE_NUMBER

Cause: Phone number doesn’t match expected format. Solution: Use 7–15 digits, optionally starting with +. Example: +77012345678

​
Files in ZIP not found

Cause: Invalid archive structure. Solution:
  • All audio files must be at the root of the ZIP (no folders)
  • File names must exactly match the audio_file_name values in CSV

​
Limits Reference

ConstraintValue
Audio file size50 MB max (single upload)
CSV/ZIP size50 MB max (batch upload)
Presigned URL validity1 hour (3600 seconds)
Phone number7–15 digits, may start with +
Audio formats.wav, .mp3, .flac, .ogg, .aiff, .au
Archive format.zip only
Metadata format.csv or .xlsx
SegmentsAt least one segment must exist in your organization