# Production checklist

Use this list before you switch an integration to a live key. Each item links to the page that explains it in detail.

## Keys and secrets

- [ ] The live key is stored in a secret manager or environment variable, never in source code, a browser or mobile app, or an agent prompt.
- [ ] Each service and environment has its own key, with only the [scopes](/docs/authentication#scopes) and countries it needs.
- [ ] Live keys have a **monthly credit limit** that matches your expected volume, so a bug cannot spend your whole balance.
- [ ] Your logs never contain the `Authorization` header or a full key. Log the key ID (`key_…`) and request IDs instead.
- [ ] You know how to rotate a key: create the new one, deploy it, check traffic, revoke the old one. See [revoke a key](/docs/authentication#revoke-a-key).
- [ ] At least two people in your team are owners or admins of the workspace.

## Idempotency

- [ ] Every intended valuation gets its own `Idempotency-Key` (REST header) or `idempotency_key` (MCP argument), derived from something stable such as your listing ID plus a revision number.
- [ ] Retries after a network failure reuse the **same key and the same body**.
- [ ] A deliberate new attempt after a confirmed refusal or failure uses a **new key**.
- [ ] You handle `409 idempotency_conflict` as a bug in your key scheme, not as a retryable error.

See [idempotency](/docs/concepts/idempotency).

## Retries and backoff

Retry only what can succeed, and use the right key:

| Situation | Codes | What to do |
| --- | --- | --- |
| No response (timeout, connection reset) | none | Retry with the **same** key and body. You get the recorded outcome if the first attempt finished. |
| Rejected before it started | `rate_limited`, `concurrency_limited`, `engine_busy`, `rate_limit_unavailable` | Wait `retry_after` seconds (REST also sends `Retry-After`), then retry with the **same** key. |
| Still running | `request_in_progress` | Wait a second or two, then retry with the **same** key. |
| Temporary service failure, recorded | `engine_unavailable`, `engine_timeout`, `engine_invalid_response`, `request_timeout`, `resolution_*`, `image_timeout`, `image_unavailable` | Back off (for example 2, 4, 8 seconds, up to a few attempts), then retry with a **new** key. Replaying the old key returns the same recorded failure. |
| Input problem | `invalid_request`, `missing_mileage`, `vehicle_not_identified`, `catalogue_id_conflict`, `vehicle_out_of_range`, `unsupported_vehicle`, `precision_below_minimum`, `payload_too_large`, `unknown_catalogue_id` | Do **not** retry unchanged. Fix the input, then send it with a new key. |
| Account or permission problem | `unauthenticated`, `invalid_api_key`, `key_revoked`, `insufficient_scope`, `country_not_enabled`, `organization_suspended`, `insufficient_credits`, `key_spend_limit_reached` | Do **not** retry. Alert a person. |
| Our configuration or a bug | `engine_misconfigured`, `internal_error` | Do **not** retry in a loop. Contact support with the request ID. |

- [ ] Your client follows this table, using the `code` field, never the `detail` text.
- [ ] Retries are bounded, with exponential backoff and jitter.
- [ ] Nothing loops on `insufficient_credits`, `key_spend_limit_reached` or validation errors.

The [error reference](/docs/errors) lists every code with its recovery steps.

## Rate and concurrency limits

- [ ] You know your workspace's limits: by default 60 valuation requests per minute (shared by valuations, selling-time forecasts, read-backs and account checks), a separate 60 vehicle requests per minute (normalization and VIN, HSN/TSN and plate lookups), 120 catalogue requests per minute and 4 live valuations, forecasts and normalizations in flight at once. `GET /v1/account` returns your `rate_limit_per_minute`.
- [ ] Batch jobs use a bounded worker pool (at most 4 concurrent live valuations by default) and pace themselves with the `RateLimit-Remaining` and `RateLimit-Reset` headers.
- [ ] Interactive traffic and batch jobs do not compete for the same limits, or batches yield to interactive use.

See [rate & concurrency limits](/docs/concepts/limits) and [batch valuations](/docs/guides/batch-valuations).

## Timeouts

- [ ] Your HTTP client timeout for `POST /v1/valuations` is at least 10 to 15 seconds. The service works within an eight-second processing budget plus up to two seconds of waiting for a concurrency slot, so a shorter timeout cuts off requests that would have succeeded.
- [ ] After a client-side timeout you retry with the **same** idempotency key, so a request that did finish is not charged twice.

## Refusals and precision

- [ ] Your code checks `status` on every valuation. Only `valued` has a price.
- [ ] You decide what to do when mileage is unknown: ask for it, or deliberately opt in to the fixed baseline with `options.allow_mileage_estimation`. See [refusals & missing mileage](/docs/guides/refusals-and-mileage).
- [ ] If you need a minimum quality, you send `options.min_precision`, which refuses weaker results for free.
- [ ] You store catalogue IDs from the resolved vehicle and send them back on revaluation.

## Presenting results

- [ ] Every price is shown with its currency and price basis (`price_basis_description`), and ideally its 80% interval and precision grade.
- [ ] You never present a valuation as an offer, an appraisal or a guaranteed sale price.
- [ ] `notes` and `attributions` are stored with the result, and any `attribution_text` is displayed where the data is shown. See [show notes & attributions](/docs/guides/notes-and-attributions).
- [ ] Test-key results never reach end users. They carry `mode: "test"`, `model.synthetic: true` and a `synthetic_result` note.

## Monitoring by request ID

- [ ] You log the body's `request_id` (`val_…`) for every valuation, including refusals and failures. It is the ID that the console, `GET /v1/valuations/{id}` and support understand.
- [ ] For errors without a recorded valuation (for example `401` or `429`), you log the Problem's `request_id` too. It is the HTTP request ID, also in the `X-Request-Id` response header. A valuation's `val_…` ID is in the body's `request_id` and in the `X-Valuation-Id` header, never in `X-Request-Id`.
- [ ] Your service checks `GET /v1/account` at startup and alerts when it fails.
- [ ] Someone watches **Usage** (daily, weekly or monthly, with CSV export) and **Billing** for unexpected spend and a falling credit balance.
- [ ] When you investigate, you look the request up in **Request logs**, which you can filter by status (valued, refused, failed, pending) and by request ID.
- [ ] You alert on a rising share of `failed` results and on any `engine_misconfigured` or `internal_error`.

## Go-live steps

1. Run your integration tests against a test key. See [testing](/docs/guides/testing).
2. Verify your email and check your credit balance under **Billing**. [Contact sales](/contact-sales) for a credit package if you need more than the signup credits.
3. Create a live key with narrow scopes, the countries you serve and a monthly credit limit.
4. Deploy the key. Start with a small share of traffic.
5. Compare the first live results with your expectations in **Request logs**. Check precision grades and warnings, not only prices.
6. Raise traffic gradually. [Contact sales](/contact-sales) before you need higher rate or concurrency limits.
