Header di richiesta

Tre header opzionali riconosciuti dal gateway: due portano il tuo contesto di tracing fino ai nostri log, uno mantiene una conversazione sullo stesso upstream perché il caching dei prompt continui a fare centro. Ometterli non cambia nulla.

Header	Cosa fa il gateway	A cosa serve
`X-Trace-Id`	Restituito invariato nella risposta; scritto nel log di accesso.	Collegare una chiamata al tuo sistema di tracing.
`X-Span-Id`	Restituito invariato nella risposta; scritto nel log di accesso.	Identificare un singolo span in quella traccia.
`X-Session-Id`	Restituito invariato. Richieste consecutive con lo stesso valore vengono fissate allo stesso canale e alla stessa chiave upstream.	Mantenere caldo il caching dei prompt lungo una conversazione.
`X-Request-ID`	Il tuo valore non viene adottato. Torna come `X-Client-Request-ID`; l'`X-Request-ID` della risposta è sempre lo UUIDv7 generato dal gateway.	L'identità della chiamata lato gateway: citala in un ticket di supporto.

Come inviarli

curl https://synthorai.io/v1/chat/completions \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: conv-8f3a2b" \
  -H "X-Trace-Id: 7c1d9e40f2b84a17" \
  -H "X-Span-Id: 2f9b41c8" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Affinità di sessione

Una voce di cache vive su una sola chiave API presso il provider. Un canale può avere più chiavi e, senza un indizio, il gateway distribuisce le chiamate tra queste: il secondo turno di una conversazione può finire su una chiave che non ha mai visto il tuo prefisso e ripagare il costo di scrittura.

Invia lo stesso valore a ogni chiamata di una conversazione e un valore diverso per un'altra conversazione. Nulla viene memorizzato lato server e nulla scade: il valore viene sottoposto ad hash per scegliere canale e chiave, quindi lo stesso valore risolve sempre allo stesso modo.

Sui due endpoint compatibili OpenAI - /v1/chat/completions e /v1/responses - puoi omettere l'header: se il corpo della richiesta contiene prompt_cache_key, il gateway lo usa come chiave di affinità. Su /v1/messages e sugli endpoint Gemini invia l'header.

L'affinità è best effort: decide solo quale canale scegliere tra candidati di pari rango. Failover, cooldown per rate limit, retry e una preferenza di routing esplicita hanno sempre la precedenza. Il prezzo di listino di un modello è lo stesso su ogni canale che possiamo scegliere.

Limiti

128 byte ciascuno. I valori più lunghi vengono troncati. Un valore con caratteri di controllo o fuori dall'ASCII stampabile viene scartato del tutto: non restituito, non registrato. Questi valori finiscono in un header di risposta e in una riga di log, il che tiene fuori header e log injection.
Si fermano al gateway. Nessuno dei tre viene inoltrato al provider del modello: la richiesta in uscita porta solo autenticazione, content type e header specifici del provider.
Nessuno identifica una chiamata ai fini della fatturazione. Fatturazione, deduplicazione e riconciliazione si basano sull'X-Request-ID del gateway, mai su un valore sotto il tuo controllo.

Quando qualcosa va storto

Indica l'X-Trace-Id inviato oppure l'X-Request-ID della risposta: con uno dei due troviamo la chiamata esatta.
Il tuo trace ID compare anche sulla richiesta in Analisi di utilizzo, così puoi trovare la chiamata prima di aprire un ticket.
Per verificare che l'affinità funzioni, invia più volte lo stesso prefisso lungo con un unico X-Session-Id e guarda le colonne Cache R e Cache W in Analisi di utilizzo: la prima chiamata scrive nella cache, le successive dovrebbero leggerla. Cambia il valore e la scrittura dovrebbe ricomparire.

Vedi anche: Prompt Caching · Usage Analytics