Unified error shape

Every error is wrapped in an error object with four fixed fields: code (the error code), message (a human-readable description), details (extra context), and request_id (this call’s identifier).

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "issues": [
        { "field": "text", "message": "String must contain at most 5000 character(s)" }
      ]
    },
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

HTTP status codes

• 200 OK — successful request.
• 400 Bad Request — parameters violate the spec.
• 401 Unauthorized — key missing, invalid, or revoked.
• 404 Not Found — route or resource does not exist.
• 409 Conflict — duplicate name or term.
• 413 Payload Too Large — audio exceeds the limit (JSON/Base64 path: 1 MB raw, audio_too_long; multipart file: 15 MB, file_too_large).
• 429 Too Many Requests — RPM or period quota exceeded (rate_limited_* / quota_exceeded_*).
• 500 Internal Server Error — server-side fault.
• 502 Bad Gateway — processing failed (translation_failed / asr_failed).
• 503 Service Unavailable — temporarily unavailable.
• 504 Gateway Timeout — processing timed out.

Common error codes

These can appear from any endpoint:

• validation_error (400) — request body validation failed; details.issues lists field-level errors.
• unauthorized (401) — key missing, invalid, or revoked.
• not_found (404) — route does not exist.
• internal_server_error (500) — server-side fault.
• service_unavailable (503) — service temporarily unavailable; retry later.

Translation error codes

• model_not_found (400) — the specified model code does not exist.
• content_policy_violation (400) — content violates the safety policy.
• dictionary_type_mismatch (400) — dictionary ID points to a type that doesn’t match the parameter (e.g. a forced_replacement dictionary passed as the vocabulary parameter).
• dictionary_not_found (404) — the specified dictionary does not exist.
• translation_failed (502) — translation service temporarily unavailable.
• translation_timeout (504) — translation request timed out.

Speech recognition error codes

• unsupported_audio_format (422) — audio format cannot be detected.
• asr_audio_decode_error (422) — Base64 is corrupt, or the content doesn’t match the declared format.
• asr_content_policy_violation (400) — content violates the safety policy.
• audio_too_long (413) — the JSON (Base64) path's audio exceeds the 1 MB raw limit; use multipart for larger files.
• file_too_large (413) — the multipart upload exceeds the 15 MB limit.
• asr_service_busy (503) — the speech recognition service is busy; back off and retry.
• asr_failed (502) — speech recognition service temporarily unavailable.
• asr_timeout (504) — transcription request timed out.

Dictionary error codes

• dictionary_not_found (404) — the specified dictionary does not exist.
• term_not_found (404) — the specified term does not exist.
• duplicate_name (409) — duplicate dictionary name.
• duplicate_term (409) — duplicate term within the same dictionary.

Report an issue

Include request_id when reporting an issue — it lets us locate the full server-side context for this exact call. Every error response carries request_id, including SSE error events.