# Best practices

Habits that keep an app on the API cheap, steady and safe.

1. [Keep your keys safe](#1-keep-your-keys-safe).
2. [Pin the model](#2-pin-the-model).
3. [Bound each request](#3-bound-each-request).
4. [Plan for failure](#4-plan-for-failure).
5. [Do repeated and patient work once](#5-do-repeated-and-patient-work-once).
6. [Watch what you spend](#6-watch-what-you-spend).
7. [Keep the wait short and the thinking in room](#7-keep-the-wait-short-and-the-thinking-in-room).

## 1. Keep your keys safe

| Do | Why |
|---|---|
| Read the key from the environment: `OPENDUNES_API_KEY` | a key written in the code ends up in the repository, and from there in every copy of it |
| Keep the key on your server, never in a browser page or a mobile app | anyone who opens the page reads the key and spends your balance |
| Make one key for each app, up to 10 on an account | a key you pause or delete stops one app, and the others keep running |
| Give each key a cap in DA and a reset: daily, weekly or monthly | a loop that runs away stops at the cap, with a 402 on that key only: [Limits](/docs/limits) |
| Tag each key *Production* or *Test* | the test traffic and the real traffic stay apart in your usage |
| Allow each key only the models its app calls | a key that cannot call a model cannot be made to spend on it |
| Keep the management key out of the apps | it runs your account and never calls a model: [Your account through a management key](/docs/your-account-through-a-management-key) |

<div class="dont">
<p>Don't share one key between your shop and your tests. A test that loops spends the cap the shop needs.</p>
</div>

## 2. Pin the model

| Do | Why |
|---|---|
| Send a full model ID, such as `anthropic/claude-sonnet-4.5`, in production | the same ID answers the same way tomorrow |
| Use a `-latest` alias in a script you watch, not in an app you do not | the alias moves to a newer model without a change in your code: [Latest model and suffixes](/docs/latest-model-and-suffixes) |
| Copy the ID from the catalogue | a typed ID that is nearly right is a 404 |

## 3. Bound each request

| Do | Why |
|---|---|
| Set the answer's limit yourself, `max_tokens` | a request that leaves it open is given a limit your wallet can pay, which may be shorter than you want; one you set is never raised |
| Stream a long answer: [Streaming](/docs/streaming) | the reader sees the first words at once, and the connection does not sit idle |
| Ask for the shape you need: [Structured outputs](/docs/structured-outputs) | a reply in your shape needs no guessing in your code |
| Send only the context the answer needs | every token sent is read, and charged |

## 4. Plan for failure

| Do | Why |
|---|---|
| Name fallbacks: [Fallbacks](/docs/fallbacks) | when a model or its provider cannot answer, the next one does, and the user sees an answer |
| Retry only a 408, 429, 500, 502, 503 or 504, and a 402 that carries `Retry-After` | the same request can pass on a second try; a 400 or a 401 never will |
| Wait the seconds in `Retry-After` when the answer sends it, and wait longer each time when it does not | a retry sent at once meets the same limit |
| Stop at a few tries | a request that fails five times has a cause that waiting will not fix |
| Read `error.message` before you retry | the body says why, and a 402 names the limit that stopped it |

What to do on every status: [Errors and retries](/docs/errors-and-retries).

<div class="watch-out">
<p>A retry of a request that already ran is a second request, and it is charged. Retry what failed, not what answered.</p>
</div>

## 5. Do repeated and patient work once

| Do | Why |
|---|---|
| Cache an identical request: [Response cache](/docs/response-cache) | a copy answers at no charge, with no model running |
| Mark a long prompt that repeats, to pay the cache-read price for its start: [Caching](/docs/caching) | the part that does not change is read once |
| Send work that can wait as a batch: [Batches](/docs/batches) | the answer comes later, at the model's batch price |

<div class="dont">
<p>Don't cache an answer that must read differently each time. A copy comes back word for word.</p>
</div>

## 6. Watch what you spend

| Do | Why |
|---|---|
| Log `usage.cost` from every answer | it is what that request cost, in DA |
| Read `X-Balance-Available` on an answer that is not streamed | it is the balance left after the charge |
| Read the balance from a script that holds the management key: [Your account through a management key](/docs/your-account-through-a-management-key) | a streamed answer carries no balance header, and one script can warn you before the wallet is empty |
| Log `model` from every answer | a router names the model it picked, and that is the one that was charged |
| Deposit before the balance runs out: [Balance and charges](/docs/balance-and-charges) | a request the wallet cannot pay for is a 402 |

## 7. Keep the wait short and the thinking in room

| Do | Why |
|---|---|
| Name a low `reasoning.effort` for simple work, and a high one only where the answer needs it | a model that reasons writes its thinking before its answer, so a lower effort ends sooner and costs less: [Reasoning](/docs/text#reasoning) |
| Raise `max_tokens` when you raise the effort | a thinking effort is a share of the answer limit: the thinking and the answer fit inside `max_tokens` together, so a higher effort under a small limit leaves a shorter answer |
| Set `max_tokens` to what the answer needs, not to the model's longest | a request that names a limit is held whole: the longest answer it may take is paid for before it starts, so a limit far above the need can get a 402, or wait for money your running requests hold, when a smaller one would have run |
| Leave the effort out when you would rather have an answer than a refusal | when the balance is short, an effort you left out drops so that an answer still comes; an effort or a thinking budget you named that the balance cannot pay is refused with a 402 |
| Stream the answer: [Streaming](/docs/streaming) | the reader sees the first words while the rest is written |
| Send only the context the answer needs | a shorter input is read sooner, and charged less |

<div class="watch-out">
<p>A limit you name is never lowered, and a limit above the model's longest answer becomes the model's longest. What the request holds, and what comes back unused: <a href="/docs/balance-and-charges#how-a-request-is-charged">How a request is charged</a>.</p>
</div>
