Request ID Header Change: avalai-request-id Replaces x-request-id

Date: 2026-08-16 / (1405-05-25)

Summary

AvalAI now returns its request ID in the dedicated avalai-request-id response header. Because some CDNs reuse x-request-id for their own tracing, AvalAI returns both headers with the same value during a 60-day transition window that ends on 2026-10-15. After that date, only avalai-request-id will be returned, and any observed x-request-id may belong to a CDN.

---

Details

Why the change

Some CDNs that sit in front of API origins set their own x-request-id header and can overwrite it. When a request passes through such a CDN, the observed value may identify the CDN hop rather than your AvalAI request, which makes cost lookup and support traces ambiguous.

To keep the request identifier unambiguous, AvalAI now returns it in the dedicated avalai-request-id header. The identifier itself does not change: it is still a UUID v7, it still supports the /user/v1/transactions/lookup endpoint, and it matches the request_id fields returned in response bodies such as the Videos API.

Transition window

Phase	Date	Behavior
Window opens	2026-08-16	Responses include both avalai-request-id and x-request-id with the same UUID
Window closes	2026-10-15	Last day AvalAI returns x-request-id
After the window	After 2026-10-15	Only avalai-request-id is returned by AvalAI; any x-request-id may come from a CDN

During the 60-day window, reading either header resolves to the same request. Update your code to read avalai-request-id before the window closes.

Representative response headers

x-ratelimit-limit-requests: 1500
x-ratelimit-remaining-requests: 1499
x-ratelimit-limit-tokens: 30000000
x-ratelimit-remaining-tokens: 29999827
x-ratelimit-reset-requests: 50s
x-ratelimit-reset-tokens: 50s
x-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e
avalai-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e

Request example

curl -i https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Return a one-line health check."
      }
    ]
  }'

The -i flag prints the response headers so you can verify both request ID headers during the transition window.

Migration examples

Read avalai-request-id from response headers. During the window you can keep a fallback to x-request-id; remove it before 2026-10-15.

Bash

# Inspect the new header on any response
curl -sI -X POST https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "hi"}]}' \
  | grep -i "avalai-request-id"

# avalai-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e

Python

import requests

response = requests.post(
    "https://api.avalai.ir/v1/chat/completions",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "hi"}]},
)

# New header (required after 2026-10-15)
request_id = response.headers.get("avalai-request-id")

# Transition-window fallback (remove before 2026-10-15)
request_id = response.headers.get("avalai-request-id") or response.headers.get(
    "x-request-id"
)

print(f"Request ID: {request_id}")

JavaScript

const response = await fetch("https://api.avalai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVALAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-5.4-mini",
    messages: [{ role: "user", content: "hi" }],
  }),
});

// New header (required after 2026-10-15)
const requestId = response.headers.get("avalai-request-id");

// Transition-window fallback (remove before 2026-10-15)
const fallbackId =
  response.headers.get("avalai-request-id") ?? response.headers.get("x-request-id");

console.log(`Request ID: ${requestId}`);

OpenAI SDK

The OpenAI SDKs expose raw response headers through the with_raw_response API:

raw_response = client.chat.completions.with_raw_response.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "hi"}],
)
completion = raw_response.parse()

request_id = raw_response.headers.get("avalai-request-id")

See the Response Headers reference for the full SDK and LangChain patterns.

What this means for AvalAI users

• Request IDs remain UUID v7 values with unchanged semantics for cost lookup and support
• Both headers are returned until 2026-10-15, so no immediate breakage occurs
• After 2026-10-15, parse avalai-request-id and stop trusting x-request-id
• Reseller cost tracking via /user/v1/transactions/lookup continues to work with the same IDs
• The X-Client-Request-Id request header and request_id body fields are unaffected

---

Related links

• Response Headers - Full header reference and migration timeline
• User API Reference - Transaction lookup using the request ID
• Reseller Cost Tracking Guide - Precise per-request cost tracking
• Error Handling - Correlating timeouts and failures with request IDs