Claude API best practices

Match the model to the task, not the other way around

The most reliable Claude API best practice is to stop sending every request to the strongest model. Route each call to the cheapest model that can actually do the work, cache the context you resend, stream anything a human is waiting on, and retry failures with backoff instead of tight loops. Everything below is the working detail behind those moves.

On apiToken.sale every supported model shares one API key and one prepaid balance, so routing is a one-line change of the model ID in the request — no extra accounts, no per-model billing setup. A flat 50% B2C discount applies across providers regardless of which model a task lands on, which makes downshifting to Haiku or Sonnet a pure win.

Escalate deliberately, not by default. A common pattern in agents: run the loop on claude-sonnet-5, detect failure signals (repeated tool errors, self-corrections going in circles), and re-issue only that step against claude-opus-4-8. You pay Opus prices on the few steps that need it instead of the whole session.

Model selection for coding workloads, compared in depth →

See also: How to save tokens on the Claude API

Cache the context you resend on every call

If your requests carry a large stable prefix — a long system prompt, tool definitions, a codebase digest, few-shot examples — prompt caching is the single biggest cost lever after model choice. Mark the reusable blocks with cache_control and the API stores them: cache writes cost a small premium over fresh input, but subsequent cache reads cost a fraction of fresh input tokens.

curl https://router.apitoken.sale/v1/messages \
  -H "x-api-key: sk-pool-•••" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {"type": "text", "text": "...20k tokens of stable instructions...",
       "cache_control": {"type": "ephemeral"}}
    ],
    "messages": [{"role": "user", "content": "Summarize ticket #4821"}]
  }'

Two rules make or break cache hit rates. First, the cached prefix must be byte-identical between calls — even a timestamp injected at the top of the system prompt invalidates everything after it, so put volatile content at the end. Second, the default ephemeral cache lives only a few minutes and refreshes on each hit, so it rewards chatty workloads: agents, chat sessions, batch jobs that reuse one context.

Caching is not free storage. A one-off request over a long document pays the cache-write premium with no reads to amortize it. Cache only what you will resend at least twice inside the TTL window.

Stream anything a human is waiting on

Set stream: true and the API returns tokens over server-sent events as they are generated instead of one blocking response. Streaming costs the same tokens as a buffered call, but the perceived latency drops from "the whole answer" to "the first token", which is often a second or less. For chat UIs this is the difference between a spinner and a reply that feels instant.

Streaming matters just as much for agents. Reading events as they arrive lets you start parsing a tool call the moment its JSON block closes, surface progress to the user, and abort early when the output is clearly going wrong — a killed stream means you stop paying for output tokens you were going to discard anyway.

With streaming, the authoritative token usage arrives in the final message_delta event, not up front. Always read the terminal usage before logging cost or updating budgets — never estimate from character counts.

Retry 429s and 5xx with backoff, never in tight loops

apiToken.sale does not publish a fixed requests-per-minute table: a 429 signals a gateway or upstream capacity limit, and the correct response is patience, not pressure. Honor the Retry-After header when it is present, otherwise retry with exponential backoff plus random jitter, and lower client-side concurrency before raising request rates.

1. 01Catch the error and classify it. Retry 429 and 5xx only; a 400, 401 or 403 will fail identically forever, so fix the request or the key instead of retrying.
2. 02Wait for the Retry-After interval if the header exists; otherwise wait roughly 1s, then 2s, 4s, 8s — doubling each attempt with a random jitter so parallel workers do not retry in lockstep.
3. 03Cap attempts (three to five is typical) and then fail the task visibly. Silent infinite retries burn balance and hide outages.
4. 04If 429s persist at your normal load, reduce concurrency and contact support about sustained higher throughput rather than engineering around it.

Rate limits, Retry-After and throughput on apiToken.sale →

One key per environment, guardrails switched on

Create a separate, clearly named key for each environment or application — prod-backend, staging-ci, local-dev — instead of sharing one key everywhere. When a key leaks, you revoke exactly that key and the rest of your fleet keeps running; with a shared key, one leak means an emergency rotation of every client at once.

The dashboard offers two per-key guardrails, and both are worth setting: an optional lifetime spending limit, which caps the total a key can ever draw from your balance, and an expiration date, after which the key simply stops working. Size the lifetime limit to what that environment should legitimately consume, and give short-lived projects short-lived keys.

• Keep keys in a secret manager or environment variables — never in source control, client-side code or tickets.
• Treat any key that touched a public place (a commit, a log line, a screenshot) as compromised: revoke first, investigate after.
• Cap max_tokens per request to what the response actually needs, so a runaway prompt cannot inflate a single call.

The full key-hygiene playbook →

Audit the token breakdown, not just the balance

Every request in your apiToken.sale dashboard is itemized by model, provider and token bucket — input, output and cache legs. Review that breakdown weekly. Cost regressions almost always show up there first: input tokens creeping up because someone started resending full history, output tokens ballooning because max_tokens was raised "just in case", cache reads collapsing after a prompt reorder.

The economics stack in your favor. Requests are metered at exact provider rates, then the flat 50% B2C discount is applied, and the net draws from a prepaid balance that never expires — so every token you eliminate through caching, routing and tighter context is a token you also never paid full price for. Token tactics reduce the count; the discount reduces the price; together they multiply.

Estimate a workload before you run it with the cost calculator →

Frequently asked questions

Related guides