Request ID

Save request tracing identifiers from response headers or error details and prepare actionable troubleshooting information.

Why save a Request ID

A Request ID associates one API request with the platform's processing records. When a request fails, returns an unexpected result, times out, or raises a billing question, saving the Request ID reduces the need to share the complete request body and helps locate the corresponding request.

Header names can vary by protocol, endpoint, or gateway path. When checking response headers, look for these names in order:

x-request-id: REQUEST_ID
request-id: REQUEST_ID
x-oneapi-request-id: REQUEST_ID

Use the actual response

Not every endpoint or response includes every header. Save whichever Request ID is present. Some error responses may also include a Request ID in the error body.

Use cURL to inspect response headers

Set the current site's Base URL and API Key in a trusted terminal environment. The -i option prints both the response headers and body:

export AGTCLOUD_BASE_URL='https://api.agtcloud.cn/v1'
export AGTCLOUD_API_KEY='your-api-key'

curl -i "${AGTCLOUD_BASE_URL:?}/chat/completions" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${AGTCLOUD_API_KEY:?}" \
  --data '{"model":"MODEL_ID","messages":[{"role":"user","content":"Hello"}]}'

Do not share terminal history or screenshots that contain the complete Authorization value.

Read it with Python

import os
import requests

base_url = os.environ["AGTCLOUD_BASE_URL"]
api_key = os.environ["AGTCLOUD_API_KEY"]

response = requests.post(
    f"{base_url}/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "MODEL_ID",
        "messages": [{"role": "user", "content": "Hello"}],
    },
    timeout=60,
)

request_id_headers = (
    "x-request-id",
    "request-id",
    "x-oneapi-request-id",
)
request_id = next(
    (response.headers.get(name) for name in request_id_headers if response.headers.get(name)),
    None,
)
print("request_id:", request_id)
print("status:", response.status_code)

Production code should limit the response body length written to logs and redact prompts, file contents, and user data.

Read it with JavaScript

const response = await fetch(`${process.env.AGTCLOUD_BASE_URL}/chat/completions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGTCLOUD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'MODEL_ID',
    messages: [{ role: 'user', content: 'Hello' }],
  }),
});

const requestIdHeaderNames = [
  'x-request-id',
  'request-id',
  'x-oneapi-request-id',
] as const;
const requestId =
  requestIdHeaderNames
    .map((name) => response.headers.get(name))
    .find((value) => value !== null) ?? null;

console.log({ requestId, status: response.status });

This example is for server-side environments only. A browser must not hold a long-lived API Key.

What to include when requesting troubleshooting help

Information	Example	Required?
Request ID	`REQUEST_ID`	Provide it when present in the response
Request time	`2026-08-19 14:30 +08:00`	Yes
Method / Path	`POST /v1/chat/completions`	Yes
Model ID	Provide the exact value after redaction	Yes
HTTP Status	`429`	Yes
Error code and short message	Remove sensitive content	Recommended
SDK and version	`openai` SDK version	When using an SDK

Do not provide the complete API Key, authentication header, user private data, unredacted files, or complete requests and responses. A Request ID is not an API Key, but it should still be shared only when necessary for troubleshooting.

What if there is no Request ID

Still save the request time, endpoint, model, status, and error body.
Confirm that a proxy, CDN, or SDK did not discard response headers.
For streaming requests, also record the connection start and disconnect times.
For asynchronous tasks, also save the Task ID.
When requesting troubleshooting help, state that no tracing identifier was found in either the response headers or the error body.

Related pages: Errors and troubleshooting · FAQ · General conventions