Request ID and issue reporting

Complete developer guide and best practices to help you get started quickly.

Advanced

Every failed response and SSE error event carries a request_id. Include it in your issue report so we can pinpoint the exact server-side context for that single request.

request_id is the identifier for one specific API call. The server generates it on receipt and emits it as a 32-character hexadecimal string in the response. A single call has exactly one request_id; it is never reused across calls and never rebuilt or shortened.

Find request_id in an error response

In JSON mode, every error response is wrapped in an error object and request_id is one of the four fixed fields. Even when message and details only carry generic text, request_id is still returned.

JSON-mode error response example. request_id is the 32-character hexadecimal string.

json

{
  "error": {
    "code": "translation_failed",
    "message": "Translation request could not be completed.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

Find request_id in an SSE error event

When a business error occurs mid-stream, the server emits an error event in place of the remaining events and closes the stream. The payload mirrors the JSON-mode error shape, with request_id present as the same fixed field. Note that once an SSE connection is established the HTTP status is fixed at 200 — you must read the event payload to obtain request_id.

SSE error event example. The whole block is the contents of an SSE data field (formatted for readability).

json

data: {
  "type": "error",
  "data": {
    "code": "asr_timeout",
    "message": "Speech recognition request timed out.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

Include request_id when reporting an issue

Our server-side records are keyed by request_id. A single request_id maps to the full processing record of that call. When filing an issue, include the information below in this order.

request_id (paste the full 32-character string verbatim).
Endpoint path and HTTP method (e.g. POST /api/v1/translations/text).
When the request happened, with time zone (ISO 8601 recommended, e.g. 2026-05-04T14:23:55+08:00).
The error.code literal (e.g. translation_failed, asr_timeout).
Reproduction steps or a minimal reproducible example. Never paste the raw API key in the report; mask it as sk_live_••• if needed.

Reporting template

Suggested format: "[request_id] 0af76519...80319c — POST /api/v1/translations/text — 2026-05-04T14:23:55+08:00 — error.code: translation_failed — repro: [short note]". A fixed order lets us locate the request in under 30 seconds.

When request_id is null

In rare edge cases `request_id` can be null. When that happens, fall back to the timestamp (with time zone) plus the endpoint path as the reporting reference, and include the error code literal.

Why request_id, not account or IP

Account, API key label, and source IP can each match dozens or even thousands of calls in the same window; with only those fields, server-side records require row-by-row comparison and the wrong request often gets picked. request_id is the smallest 1:1 identifier — handing us a request_id is like handing us the shelf number directly, so prioritise it in every report.