# Response cache

Answer a request you have already sent from a kept copy, and pay nothing for it.

1. [Turn it on](#1-turn-it-on).
2. [Send the same request twice](#2-send-the-same-request-twice).
3. [Choose how long a copy lives](#3-choose-how-long-a-copy-lives).
4. [Ask for a fresh answer](#4-ask-for-a-fresh-answer).

This is the deep guide. The headers, the status codes and what counts as identical sit in one place: [Caching](/docs/caching#3-the-response-cache).

## 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](/docs/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.

<div class="good-to-know">
<p>A copy is kept for one key only. A second key that sends the same body gets its own first answer from the model.</p>
</div>

## 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.

```python
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"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "One line to thank a customer of a bookshop in Tlemcen.";

const body = JSON.stringify({
  model: MODEL,
  messages: [{ role: "user", content: PROMPT }],
});

for (const clear of [false, false, true]) {
  const headers = {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "X-OpenDunes-Cache": "true",
  };
  if (clear) {
    headers["X-OpenDunes-Cache-Clear"] = "true";
  }
  const response = await fetch(ADDRESS, { method: "POST", headers, body });
  const answer = await response.json();
  const status = response.headers.get("X-OpenDunes-Cache-Status");
  console.log(status, answer.usage.cost);
}
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	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."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model": model,
		"messages": []map[string]string{
			{"role": "user", "content": prompt},
		},
	})
	if err != nil {
		panic(err)
	}

	for _, clear := range []bool{false, false, true} {
		req, err := http.NewRequest("POST", address, bytes.NewReader(body))
		if err != nil {
			panic(err)
		}
		req.Header.Set("Authorization", "Bearer "+apiKey)
		req.Header.Set("Content-Type", "application/json")
		req.Header.Set("X-OpenDunes-Cache", "true")
		if clear {
			req.Header.Set("X-OpenDunes-Cache-Clear", "true")
		}

		res, err := http.DefaultClient.Do(req)
		if err != nil {
			panic(err)
		}

		var answer struct {
			Usage struct {
				Cost json.Number `json:"cost"`
			} `json:"usage"`
		}
		err = json.NewDecoder(res.Body).Decode(&answer)
		res.Body.Close()
		if err != nil {
			panic(err)
		}
		status := res.Header.Get("X-OpenDunes-Cache-Status")
		fmt.Println(status, answer.Usage.Cost)
	}
}
```

```bash cURL
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."

for clear in false false true; do
  curl -si "$ADDRESS" \
    -H "Authorization: Bearer $OPENDUNES_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-OpenDunes-Cache: true" \
    -H "X-OpenDunes-Cache-Clear: $clear" \
    -d '{
      "model": "'"$MODEL"'",
      "messages": [
        {
          "role": "user",
          "content": "'"$PROMPT"'"
        }
      ]
    }' | grep -i '^x-opendunes-cache-status'
done
```

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.

<div class="watch-out">
<p>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 <code>MISS</code>.</p>
</div>

## 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 |

<div class="do">
<p>Read <code>X-OpenDunes-Cache-TTL</code> on the answer to see how many seconds a hit has left. On a miss, it holds the full span.</p>
</div>

## 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.

<div class="dont">
<p>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 <code>temperature</code>.</p>
</div>

## Errors

The body says why. What to do on every status: [Errors and retries](/docs/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 balance cannot cover a request that has to run the model |
