Response Headers
Every request to and response from the Cachecore gateway uses HTTP headers for authentication, dependency tagging, and cache diagnostics.
Request headers (you send these)
| Header | Required | Description |
|---|---|---|
Authorization | Yes* | Bearer cc_live_xxxxx.eyJ... Preferred auth method |
X-Cachecore-Token | Yes* | Alternative auth header (backward compatibility) |
X-Cachecore-Deps | No | Base64url-encoded JSON array of dependency declarations |
*One of Authorization or X-Cachecore-Token is required. Authorization: Bearer is preferred.
Bypass mode: To skip caching entirely for a request, omit the auth token. The gateway treats a missing token as bypass mode, routing the request directly to OpenAI without cache lookup or write. When using the Python client, request_context(bypass=True) handles this automatically.
Response headers (Cachecore returns these)
| Header | Values | Description |
|---|---|---|
X-Cache | HIT_L1, HIT_L1_STALE, HIT_L2, MISS, BYPASS | Cache result for this request |
X-Cache-Similarity | 0.00–1.00 | Cosine similarity score (L2 hits); 1.00 for L1, 0.00 for MISS/BYPASS |
X-Cache-Age | integer (seconds) | Age of the cached entry; 0 for MISS/BYPASS |
Reading X-Cache
The X-Cache header encodes both the cache result and the tier in a single value:
| Value | Latency | Description |
|---|---|---|
HIT_L1 | ~5ms | Exact hash match. Response served from Redis L1 |
HIT_L1_STALE | ~5ms | Stale L1 match. Served from cache; background refresh triggered |
HIT_L2 | ~15ms | Semantic match. Response served from Redis L2 HNSW index |
MISS | 1-3s | No match. Request forwarded to OpenAI, response cached |
BYPASS | 1-3s | No auth token. Request forwarded to OpenAI, response not cached |
Dependency declaration format
The X-Cachecore-Deps header is a base64url-encoded JSON array:
[
{"dep_id": "doc:contract-123", "expected_hash": "v1"},
{"dep_id": "table:products", "expected_hash": "2024-01-15"}
]
dep_id is an arbitrary string identifying a data resource. Convention: <type>:<identifier>.
expected_hash is the data version at cache-write time. If the dependency's current hash has been updated via /v1/invalidate, cached entries tagged with it are rejected on lookup.
Debug headers
When debug mode is enabled on your project, an additional header is returned:
| Header | Description |
|---|---|
X-Cachecore-Namespace-Hint | First 12 hex characters of the namespace hash |
Useful for verifying that two requests derive the same namespace across environments.