Errors

This document describes the error model and all error responses supported by the API as defined in the OpenAPI specification.

Error Envelope

All error responses conform to a common JSON schema:

{
"error": "error_code",
"details": "Human-readable description of what went wrong"
}

• error — A concise error string describing the problem.
• details — Optional additional context that can help with debugging or client messaging.

Live session envelope

The live session endpoints (/v2/live/*) nest their error data under error so clients can branch on a stable code rather than parsing a message:

{
"error": {
  "code": "HLS_INPUT_INCOMPATIBLE",
  "type": "VALIDATION_ERROR",
  "message": "H.264 profile 'high-10' is not supported",
  "details": { "video_profile": "high-10" },
  "requestId": "req_01HZ..."
}
}

• code — Stable, machine-readable identifier. Branch on this.
• type — Broad classification, e.g. VALIDATION_ERROR, NOT_FOUND, UNSUPPORTED_OPERATION, SERVICE_UNAVAILABLE.
• message — Human-readable description.
• details — Optional object naming the specific fields that failed.
• requestId — Echoes X-Request-Id when you send one. Quote it in support tickets.

HTTP Status Codes

Endpoint-specific Error Notes

POST /v2/generate

• 400 Bad Request
  • content missing or of the wrong shape:
    • type must be text (the only supported input).
    • data is required and must contain the text to translate.
  • output validation:
    • format must be one of: hls, mp4.
    • delivery.method must be one of: stream, download, display, push.
    • delivery.config is allowed but must be an object if provided.
    • delivery.config.screenId is required when delivery.method is display.
  • context validation: must be an object; known fields have expected types if provided.
• 500 Internal Server Error
  • Failures during translation job creation, media processing, or URL presigning.

{
"error": "validation_error",
"details": "output.format must be one of: hls, mp4"
}

POST /v1/generate

• 400 Bad Request
  • Body must match the TranslationRequest schema used by v1.
  • Same content/output/context validation considerations as v2 apply.
• 500 Internal Server Error
  • Unexpected processing failures or downstream dependency issues.

{
"error": "invalid_request",
"details": "content.data is required"
}

GET /v1/status/{job_id}

• 400 Bad Request — job_id missing or invalid format.
• 500 Internal Server Error — Internal failures retrieving job status.

{
"error": "invalid_job_id",
"details": "Provide a valid job_id path parameter"
}

GET /v1/silence

• 400 Bad Request — Invalid language, signer, format, or transparent parameter, or an unsupported combination (transparent=true with explicit format=ts).
• 500 Internal Server Error — Failures generating presigned URLs for silence segments.

{
"error": "invalid language "xyz": must be one of bsl, asl"
}

{
"error": "invalid signer "foo" for language "bsl": must be one of rae"
}

{
"error": "invalid format "xyz": must be one of mp4, ts"
}

{
"error": "transparent output not available for ts format"
}

{
"error": "presign_failed",
"details": "Temporary failure generating presigned URLs"
}

POST /v2/live/sessions

• 400 Bad Request
  • Invalid sourceType: must be one of RTMP_PUSH, SRT_PUSH, HLS_PULL.
  • Missing hlsSourceUrl when sourceType is HLS_PULL.
  • Invalid outputType: must be one of HLS, RTMP, SRT.
  • Missing rtmpOutputUrl when outputType is RTMP, or outputDestinationUrl when outputType is SRT.
  • Invalid language / signer, or a combination that does not exist.
  • An HLS_PULL source that fails the picture-in-picture input contract — see the codes below.
• 401 Unauthorized — Invalid or missing API key.
• 501 Not Implemented — Live ingest, or the specific transport requested, is not provisioned for your account.
• 503 Service Unavailable — Source normalization capacity exhausted, or the RTMP ingest endpoint is temporarily unreachable. Retry with backoff.

{
"error": {
  "code": "BAD_REQUEST",
  "type": "VALIDATION_ERROR",
  "message": "hlsSourceUrl is required when sourceType is HLS_PULL"
}
}

Error codes

The three HLS_INPUT_* 400s apply to picture-in-picture sessions with an HLS_PULL source. See HLS Source Requirements for the full contract and how to fix each one.

GET /v2/live/sessions/{id}

• 404 Not Found — The specified session ID does not exist.

{
"error": {
  "code": "NOT_FOUND",
  "type": "NOT_FOUND",
  "message": "session not found"
}
}

DELETE /v2/live/sessions/{id}

• 404 Not Found — The specified session ID does not exist.

{
"error": {
  "code": "NOT_FOUND",
  "type": "NOT_FOUND",
  "message": "session not found"
}
}

Client Guidance