Error Handling

Overview

The API uses standard HTTP status codes and returns error details in a consistent format. All errors include a detail field with a human-readable message.

Error Response Format

All error responses follow this structure:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

400 Bad Request

Returned when the request is malformed or missing required parameters. Common scenarios:

No utterances detected in media (NO_UTTERANCES)
File too large (FILE_TOO_LARGE)
Missing timeline for segmentation endpoint
Invalid file format
Empty chunk data uploaded

Example:

{
  "detail": "No utterances detected in uploaded media"
}

401 Unauthorized

Returned when authentication fails. Scenarios:

Missing X-API-Key header (INVALID_KEY)
Invalid API key provided (INVALID_KEY)
API key not in allowlist (INVALID_KEY)

Example:

{
  "detail": "Invalid or missing API key"
}

You can also pass the API key as a query parameter: api_key=<client key> when custom headers are not available.

404 Not Found

Returned when a requested resource doesn’t exist. Scenarios:

Unknown live session ID
Invalid endpoint path

Example:

{
  "detail": "Unknown live session"
}

409 Conflict

Returned when there’s a conflict with the current state. Scenarios:

Concurrent SSE attach (only one SSE consumer per live session)
Wrong chunk sequence number (chunks must be uploaded sequentially)
Session already finalized
Attempting to upload to a finalized session

Example:

{
  "detail": "Only one SSE consumer may be attached to a live session at a time"
}

500 Internal Server Error

Returned when server-side processing fails. Common causes:

Downstream agent or ASR failure (ANALYSIS_FAILURE)
External service failures
Media processing errors
General pipeline failures

Example:

{
  "detail": "Analysis failed: Connection timeout"
}

SSE Error Events

SSE streams may emit error events with specific error codes:

Error Event Format

event: error
data: {"code":"ERROR_CODE","message":"Human-readable message"}

Error Codes

string

Media contained no speech above the threshold. Analysis cannot proceed.

string

Exceeded MAX_FILE_SIZE_MB (default 500 MB). Upload fails before processing.

string

Missing or incorrect API key. Verify header or query parameter.

string

Downstream agent or ASR failure. Details provided in detail field.

string

Live ASR connection failed. The live streaming session cannot continue.

string

General streaming failure. The SSE connection may close after this event.

Example SSE error:

event: error
data: {"code":"STREAM_FAILURE","message":"Streaming connection lost"}

Best Practices

Retry Logic

401 errors: Check API key configuration. Do not retry with the same key.
400 errors: Fix the request payload. Do not retry without changes.
404 errors: Verify resource IDs. Do not retry.
409 errors: Resolve the conflict (e.g., wait for current SSE consumer to disconnect). Retry after resolution.
500 errors: Implement exponential backoff. These may be transient.

Error Handling in SSE Streams

When consuming SSE streams:

Listen for error events: Always handle error events in your SSE client
Handle connection drops: Implement reconnection logic for network failures
Validate event data: Parse JSON carefully and handle malformed events gracefully
Log errors: Record error codes and messages for debugging

Example JavaScript SSE error handling:

const eventSource = new EventSource('/analyze/live/session123/events');

eventSource.addEventListener('error', (event) => {
  const errorData = JSON.parse(event.data);
  console.error(`SSE Error [${errorData.code}]: ${errorData.message}`);
  
  if (errorData.code === 'STREAM_FAILURE') {
    eventSource.close();
    // Implement retry or fallback logic
  }
});

Chunk Upload Error Handling

When uploading chunks to live sessions:

409 on wrong sequence: Use the next_chunk_seq from the previous response
404 on unknown session: Verify session ID and check if session expired
409 on finalized session: Session is complete; do not upload more chunks

Example retry logic:

def upload_chunk(session_id, chunk_data, chunk_seq):
    try:
        response = requests.post(
            f'/analyze/live/{session_id}/chunk',
            files={'chunk': chunk_data, 'chunk_seq': chunk_seq}
        )
        response.raise_for_status()
        return response.json()['next_chunk_seq']
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 409:
            # Wrong sequence - get correct sequence from error or previous response
            return get_correct_sequence(session_id)
        raise

Operational Notes

Session TTL Management

Live sessions expire after a default TTL (900 seconds). To prevent expiration:

Call POST /analyze/live/{session_id}/control with {"action": "keepalive"} during long pauses
Monitor expires_at timestamp from session start response
Upload chunks regularly to keep session active

File Size Limits

Files exceeding MAX_FILE_SIZE_MB (default 500 MB) will be rejected with a 400 error before processing begins. Check file size client-side before upload.

Prosody Fallbacks

If audio processing fails post-stream, the service still returns textual insights. Prosody fields may be empty in the response. This is not an error condition.

Error Handling & Troubleshooting

Layer	Symptom	Resolution
Authentication	`401 {"detail":"Invalid or missing API key"}`	Verify header, rotate key if unsure.
Replay stream	SSE disconnects immediately	Ensure `Accept: text/event-stream` and HTTP client supports streaming (no proxies buffering).
Live capture	`409 Session already has an active SSE stream`	Only one event consumer per session; close existing connection before re-attaching.
Chunk upload	`409 Expected chunk_seq=<n>`	Re-send the missing chunk; chunks must be sequential.
Summary	`summary_update` missing or fallback text appears	Indicates schema validation failure; check server logs for warnings.

Logs are available server-side. Look for [conversation_id] prefixes for correlated traces.

Debugging Tips

Check logs: Server-side logs are available for debugging
Verify artifacts: Check artifact_dir paths in responses for debugging
Monitor metrics: Use /metrics endpoint to watch SSE throughput and latency
Validate OpenAPI: Ensure your requests match the OpenAPI specification
Correlate traces: Look for [conversation_id] prefixes in logs for debugging specific conversations

Introduction

Endpoints

Cookbooks

Reference

Overview

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

404 Not Found

409 Conflict

500 Internal Server Error

SSE Error Events

Error Event Format

Error Codes

Best Practices

Retry Logic

Error Handling in SSE Streams

Chunk Upload Error Handling

Operational Notes

Session TTL Management

File Size Limits

Prosody Fallbacks

Error Handling & Troubleshooting

Debugging Tips

​Overview

​Error Response Format

​HTTP Status Codes

​400 Bad Request

​401 Unauthorized

​404 Not Found

​409 Conflict

​500 Internal Server Error

​SSE Error Events

​Error Event Format

​Error Codes

​Best Practices

​Retry Logic

​Error Handling in SSE Streams

​Chunk Upload Error Handling

​Operational Notes

​Session TTL Management

​File Size Limits

​Prosody Fallbacks

​Error Handling & Troubleshooting

​Debugging Tips

Overview

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

404 Not Found

409 Conflict

500 Internal Server Error

SSE Error Events

Error Event Format

Error Codes

Best Practices

Retry Logic

Error Handling in SSE Streams

Chunk Upload Error Handling

Operational Notes

Session TTL Management

File Size Limits

Prosody Fallbacks

Error Handling & Troubleshooting

Debugging Tips