Skip to main content

​
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

​
NO_UTTERANCES
string
Media contained no speech above the threshold. Analysis cannot proceed.
​
FILE_TOO_LARGE
string
Exceeded MAX_FILE_SIZE_MB (default 500 MB). Upload fails before processing.
​
INVALID_KEY
string
Missing or incorrect API key. Verify header or query parameter.
​
ANALYSIS_FAILURE
string
Downstream agent or ASR failure. Details provided in detail field.
​
LIVE_ASR_FAILURE
string
Live ASR connection failed. The live streaming session cannot continue.
​
STREAM_FAILURE
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:
  1. Listen for error events: Always handle error events in your SSE client
  2. Handle connection drops: Implement reconnection logic for network failures
  3. Validate event data: Parse JSON carefully and handle malformed events gracefully
  4. 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

LayerSymptomResolution
Authentication401 {"detail":"Invalid or missing API key"}Verify header, rotate key if unsure.
Replay streamSSE disconnects immediatelyEnsure Accept: text/event-stream and HTTP client supports streaming (no proxies buffering).
Live capture409 Session already has an active SSE streamOnly one event consumer per session; close existing connection before re-attaching.
Chunk upload409 Expected chunk_seq=<n>Re-send the missing chunk; chunks must be sequential.
Summarysummary_update missing or fallback text appearsIndicates schema validation failure; check server logs for warnings.
Logs are available server-side. Look for [conversation_id] prefixes for correlated traces.

​
Debugging Tips

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