Response cache
Answer a request you have already sent from a kept copy, and pay nothing for it.
This is the deep guide. The headers, the status codes and what counts as identical sit in one place: Caching.
1. Turn it on
The cache is off until you turn it on. There are three ways, and they work on the same copies.
| Way | Turns it on for |
|---|---|
the request header X-OpenDunes-Cache: true | that request |
| a preset that holds the cache: Presets | every request that names the preset |
| the cache setting of a key, in your dashboard | every request of that key |
A preset holds the cache beside the model and the parameters, so one name carries all of them.
When two ways disagree, the request's own header wins over the key's setting. X-OpenDunes-Cache: false switches the cache off for one request on a key that has it on.
Four routes cache: chat completions, responses, messages and embeddings.
A copy is kept for one key only. A second key that sends the same body gets its own first answer from the model.
2. Send the same request twice
Souk Bot greets every visitor of a bookshop in Tlemcen with one line. This sample sends the greeting three times: twice as it is, then once asking for a fresh answer. It prints the cache status and the cost of each.
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "One line to thank a customer of a bookshop in Tlemcen."
body = json.dumps(
{"model": MODEL, "messages": [{"role": "user", "content": PROMPT}]}
).encode()
for clear in (False, False, True):
headers = {
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
"X-OpenDunes-Cache": "true",
}
if clear:
headers["X-OpenDunes-Cache-Clear"] = "true"
request = urllib.request.Request(ADDRESS, data=body, headers=headers)
with urllib.request.urlopen(request) as response:
answer = json.load(response)
status = response.headers.get("X-OpenDunes-Cache-Status")
print(status, answer["usage"]["cost"])It prints MISS, then HIT, then MISS. The first request ran the model and kept its answer. The second came from the copy, at no charge, with no model running. The third asked for a fresh answer, so the model ran again and its answer replaced the copy.
The copy is exact. Add a space to the prompt, or reorder two fields of the body, and the request is a new one: it prints MISS.
3. Choose how long a copy lives
A copy lives 300 seconds unless you say otherwise. Send X-OpenDunes-Cache-TTL with a whole number of seconds from 1 to 86400 to change it for the copy that request keeps. The key's cache setting in the dashboard holds a default span for the key.
| Use | Span to ask for |
|---|---|
| a greeting or a fixed explanation that never changes | a day: 86400 |
| a summary of a page that changes during the day | an hour: 3600 |
| an answer you only want to survive a retry | the default, or a few seconds |
Read X-OpenDunes-Cache-TTL on the answer to see how many seconds a hit has left. On a miss, it holds the full span.
4. Ask for a fresh answer
Send X-OpenDunes-Cache-Clear: true when one answer must be written again, such as after you have changed the text a prompt refers to. The model answers, you pay for that answer, and it replaces the kept copy for the next request.
Don't turn the cache on for a request that must read differently each time, such as a new product description on every call. Every hit returns the same words, whatever the temperature.
Errors
The body says why. What to do on every status: Errors and retries.
| Status | Means |
|---|---|
| 400 | X-OpenDunes-Cache-TTL is not a whole number of seconds from 1 to 86400 |
| 401 | the key is missing or wrong |
| 402 | the balanceBalanceWhat you can spend, in DA.More on Balance and charges → cannot cover a request that has to run the model |