Response headers
The Cova-* headers CoreValue adds to a response, when each one is present, and the final cova frame on a stream.
When CoreValue forwards a request to a provider, the response you get back is the provider's response with a few Cova-* headers added. They tell you which request this was, who served it, and what it cost. Every request header you can send is on Headers.
On every forwarded response
These are set on every response that came back from a provider, streaming or not, including a provider's own error.
| Header | What it says | Example |
|---|---|---|
Cova-Id | The request's ID. Search for it on Requests, or pass it to /meta. | Cova-Id: 550e8400-e29b-41d4-a716-446655440000 |
Cova-Status | success when the provider answered HTTP 200, otherwise error. | Cova-Status: success |
Cova-Provider | The provider that served the request, after any fallback or routing by model name. Gemini is google-ai-studio. | Cova-Provider: groq |
Cova-Model | The model that served the request. It can differ from the one you asked for after a fallback, a budget Downgrade model, or routing by model name. | Cova-Model: gpt-4o-mini |
Cova-Gateway-Mode | translated when CoreValue translated an OpenAI-format request into Anthropic, Gemini or Bedrock format and mapped the reply back; otherwise passthrough. | Cova-Gateway-Mode: translated |
Present only sometimes
| Header | When it is present | What it says |
|---|---|---|
Cova-Request-Cost | Every non-streaming response. Never on a stream. | The request's cost in US dollars, to 10 decimal places. 0.0000000000 when the request failed or the model is unpriced. |
Cova-Translation-Warning | A translated request that had fields the target provider does not accept. | The dropped request fields, comma-separated, for example logprobs,top_k. |
X-Cova-Retry-Count | CoreValue retried the request at least once (a provider 429, 5xx or network failure). | How many retries were made before this response. |
Cova-Credits-Remaining | A non-streaming request paid from CoreValue credits rather than your own provider key. | Your credit balance after this request, in US dollars. |
Cova-Request-Cost-Estimate | Reserved for requests paid from credits. Not sent today. | The upfront worst-case estimate held for the request. |
Requests made with your own provider keys never carry the two credit headers.
Streaming: the final cova frame
A stream's headers are sent before the first token, when the cost is not yet known, so a streamed response has no Cova-Request-Cost. Instead, after the provider's stream ends (after data: [DONE] on OpenAI-format streams), CoreValue appends one more Server-Sent Event:
data: {"cova":{"status":"success","requestId":"550e8400-e29b-41d4-a716-446655440000","provider":"openai","model":"gpt-4o-mini","gatewayMode":"passthrough","requestCost":…}}| Field | Same as |
|---|---|
requestId, status, provider, model, gatewayMode | The headers above |
translationWarning | Cova-Translation-Warning, when present |
requestCost | The request's cost. Left out when the cost is $0 — an unpriced model, or a stream that returned no usage. |
The frame is added only to text/event-stream responses, such as OpenAI-format chat completions and Anthropic Messages. A Bedrock invoke-with-response-stream (a binary event stream) and a Gemini streamGenerateContent without alt=sse (streaming JSON) are passed through untouched; read their cost from GET /gateway/v1/meta/{requestId} instead, for up to five minutes after the request ends.
If your SSE client does not expect an extra event after [DONE], ignore a final chunk whose JSON has a top-level cova key. The CoreValue SDK reads it for you.
Cache hits
A response served from the cache is the provider's original response, replayed with its original headers and these three added:
| Header | What it says |
|---|---|
Cova-Cache | HIT |
Cova-Cache-Bucket-Idx | Which cached copy was returned, when you keep more than one with Cova-Cache-Bucket-Max-Size. |
Cova-Cache-Latency | How long, in milliseconds, the original request took. |
A cache hit has no Cova-Id, Cova-Request-Cost or other headers from the tables above. A miss is an ordinary forwarded response, with no Cova-Cache header.
Responses CoreValue writes itself
When CoreValue refuses a request before it reaches the provider — a bad key, a budget or key cap, a key scope, a rate limit — the response is an error body in your provider's format, without Cova-* headers. A rate-limit refusal carries Retry-After, in seconds. See Errors.
Other gateways
- MCP responses carry no
Cova-*headers. Tool calls are recorded on Requests → MCP tool calls; see Tool-call logging and cost. - A2A responses carry
Cova-Task-TraceandCova-Call-Id; see Call an agent.
Other headers from the provider are passed through unchanged, except Content-Encoding and Content-Length, which CoreValue removes because it has already decoded the body.