Production checklist

Keys

• One key per environment, minimum. Separate keys give you separate usage rows, separate caps and separate blast radius. key_name lands on every row, so this is also how you tell staging traffic from production in the log.
• Set the cap to what a bad day costs, not to what a good day costs. Each key's cap is enforced upstream, so the cap is a real ceiling rather than an alert. A runaway loop can cost at most that number. Self-serve accounts are limited to $10 per key and 3 active keys during beta.
• Never ship a key to a browser or a mobile binary. A key can read your entire usage log, including logged content if you enabled it, and can upload and delete case files. It cannot mint keys or raise its own cap, which is the one thing it deliberately cannot do, and that is not enough on its own.
• Rotate by minting, not by rotating, when uptime matters. POST /keys/:id/rotate invalidates the old secret immediately, so there is no overlap window. To rotate with zero failed requests, mint a second key, deploy it, confirm traffic has moved in the usage log, then revoke the first.
• Have the leak drill written down before you need it. Rotate or revoke, then read GET /keys/:id for the upstream usage and limit_remaining to see what was actually spent, and GET /usage filtered by that key to see what was actually asked.
• Verify with a call that costs nothing. GET /auth/key proves the credential works and reports the remaining cap without touching a model. It is the right post-deploy check.

Data policy: what is stored and what is not

Answer this before a firm asks, because they will.

• Decide on content logging deliberately. It is off by default. On, it is the difference between being able to debug a complaint about an answer and not. Off, it is the difference between storing privileged material and not. Both are defensible; drifting into one by accident is not.
• Delete case files when the matter closes. There is no retention timer, so this has to be something your system does. GET /files plus DELETE /files/:id is the whole API.
• Choose a routing policy if the model provider matters to you. A key can be set to no-train or zdr, which force data-collection denial upstream, or to a pinned provider. For work that cannot leave your infrastructure at all, a private-pod key restricts the request to in-house local/ models. These are key settings, so a request cannot downgrade them.
• Know where verification runs. Answer-side citation checking runs against DocketRouter's own library. On a private-pod key, any check that would reach outside the pod is switched off unless the deployment has explicitly opted in.

Rate-limit headroom

A key gets 120 requests per minute sustained with a burst of 40, enforced by a token bucket that refills at 2 per second. Grounded requests take seconds each, so the practical ceiling is usually your own concurrency rather than the limit.

• Size concurrency for the sustained rate, not the burst. Eight in flight is a comfortable batch setting. Forty in flight will drain the bucket in one second and then crawl.
• Honour retry-after exactly. It is the number of seconds until a token is available, rounded up. Retrying sooner is guaranteed to fail again and costs you another 429.
• Do not retry 400s. The allowlist check happens after retrieval and after the rate-limit check, so a bad model name burns a token and pays retrieval latency each time. Validate against callable_models from GET /models in your own client.
• Add a client-side queue rather than relying on retries. Headroom is not measurable from outside. A bounded queue in your own code is the only thing you control.
• Remember the timeouts. 90 seconds non-streaming, 120 seconds streaming. Set your own client timeout above those, not below, or you will abandon requests you are still billed for.

Observability

Log these four things on every call

Alerts worth having

• Degraded rate. In the usage log, juiced = 1 with sources_n = 0 is a degraded request after the fact. Alert on the share over a rolling hour, not on single events.
• Fabrication rate. citations_not_found per request, and fakes_caught in the totals.
• p95 latency. latency_ms and retrieval_ms are separate columns, so you can tell a slow model from a slow index.
• Cost per day per key. GET /usage totals, filtered by date.
• Index health. fused_index in GET /api/health predicts degraded.index_unreachable. The check does real work, so poll it at minutes, not seconds.

# Cost is an estimate at write time and truth after sync. Run this hourly.
curl -s -X POST "https://docketrouter.ai/api/v1/usage/sync?limit=200" \
  -H "Authorization: Bearer $DOCKETROUTER_API_KEY"
# {"synced":12,"unresolved":0,"remaining":0}

Interface obligations

The metadata is only worth generating if the interface acts on it.

• A fabricated citation blocks the normal presentation. Name the citations and require an explicit action to see the text. This is the one behaviour that has to be non-negotiable in your product, because it is the failure that ends up in a sanctions order.
• Unverified is not a fabrication. Render it as an amber caveat on the specific citation, with the note available. If your interface uses the same treatment for both, both signals become noise.
• Degraded gets a persistent banner. It should still be on screen when the user copies the answer out. Use different copy for an index outage and for a genuine no-match; one invites a retry, the other invites a rephrase.
• A hostile case file goes in front of a person. Show the document name and the excerpt. Someone put text in that exhibit intended for your AI, and the lawyer on the matter needs to know.
• Never render a grounding badge from one signal. Grounded means juiced is true, degraded is null, and at least one rule or case came back.
• Say that verification is an existence check. found means the case is real. It says nothing about whether it supports the proposition. Lawyers respect the distinction and distrust products that blur it.

Failure drills

Run each of these once against a real key before you launch.

When something goes wrong

1. Find the request id. From your logs, the x-docketrouter-request-id header, docketrouter.request_id, or the text of a 502 message, which embeds it.
2. Pull the row. GET /usage/:request_id returns the provider that served it, exact token counts, retrieval time, the verification report, the upstream error message, and the content if the key had logging on.
3. Check whether it was grounded. sources_n at 0 with juiced at 1 means the answer was degraded, which explains a large share of "the answer was wrong" reports on its own.
4. Check the provider. Two identical requests can be served by different providers and different quantizations. If quality varies between them, pin one with docketrouter.pin and compare.
5. Mail us with the request id. hello@docketrouter.ai. Without it, nobody can find anything.