Skip to main content

Request IDs

Every response from the Inference API includes an X-Request-Id header. This ID identifies a single request end-to-end in our logs and traces, so quoting it in a support ticket lets us find exactly what happened to your request.

Reading the Request ID​

The header is present on every response, including streaming responses and errors such as 401, 429, and 5xx.

bash
1234567
curl -i https://api.inference.nebul.io/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
123
HTTP/2 200
content-type: application/json
x-request-id: 4f1c0a9e-9c3a-4a3b-9a6f-2f1f7b0f5d21

With the OpenAI SDK, use the raw-response helpers to get at the headers:

python
1234567891011121314
from openai import OpenAI


client = OpenAI(
    api_key="sk-your-api-key-here",
    base_url="https://api.inference.nebul.io/v1"
)


response = client.chat.completions.with_raw_response.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Hello"}]
)


print(response.headers.get("x-request-id"))
completion = response.parse()  # the usual ChatCompletion object

For failed requests, read it from the exception's response:

python
12345678910
from openai import APIStatusError


try:
    completion = client.chat.completions.create(
        model="openai/gpt-oss-120b",
        messages=[{"role": "user", "content": "Hello"}]
    )
except APIStatusError as e:
    print(e.status_code, e.response.headers.get("x-request-id"))
    raise
tip

Log the request ID alongside your own application logs for every non-2xx response. It costs almost nothing and turns "the API failed yesterday afternoon" into a single traceable request.

Supplying Your Own Request ID​

Send an X-Request-Id header with your request and the API will use that value instead of generating one. It is echoed back in the response and used in our logs and traces, which lets you correlate your own trace or job ID with our side of the call.

bash
12345678
curl -i https://api.inference.nebul.io/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "X-Request-Id: 7c9d2f1e-3b64-4a5f-8a1d-0c2e4b6a8f30" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

With the OpenAI SDK, pass it through extra_headers:

python
12345
completion = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"X-Request-Id": "7c9d2f1e-3b64-4a5f-8a1d-0c2e4b6a8f30"}
)

Requirements​

RuleDetail
Header nameX-Request-Id (HTTP header names are case-insensitive, so x-request-id is fine)
Maximum length64 bytes
Minimum length1 byte - an empty header value is ignored
Allowed charactersAny valid HTTP header value (printable ASCII); no format is enforced
UniquenessNot enforced, but strongly recommended - see below

If the value you send is empty or longer than 64 bytes, it is silently ignored and the API generates an ID instead. The response still contains an X-Request-Id, but it will not be the value you sent, so check the response header if you rely on the round-trip.

Recommendations​

  • Use a UUID (or your existing trace ID) unless you have a reason not to. It fits in 64 bytes and is unique by construction.
  • Use a fresh ID per attempt. If you retry a request with the same ID, both attempts share one identifier and we cannot tell them apart. Either generate a new ID per attempt or add an attempt suffix, e.g. ...-f30/2.
  • Do not treat it as an idempotency key. The request ID is for tracing only - it does not deduplicate requests, and sending the same ID twice will run the request twice.
  • Do not put sensitive data in it. The value ends up in logs and traces.

Generated Request IDs​

If you do not send a usable X-Request-Id, the API generates one for you. Depending on how the request is traced, this is either the request's 32-character hexadecimal trace ID or a random UUID. Both are safe to quote in a support ticket; do not parse or make assumptions about the format.

Reporting a Problem​

When something goes wrong, include the request ID together with the model ID, the endpoint path, and the full error response body. See Getting the Fastest Resolution for the complete checklist.

Last updated on