Get started / Production checklistView Markdown ↗
Beta
AutoUncle Data Services is in beta. The API, MCP tools and agent skill may change often, including breaking changes, until version 1.0. Read the changelog before you upgrade an integration.
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 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
Authorizationheader 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.
- [ ] 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) oridempotency_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_conflictas a bug in your key scheme, not as a retryable error.
See 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
codefield, never thedetailtext. - [ ] Retries are bounded, with exponential backoff and jitter.
- [ ] Nothing loops on
insufficient_credits,key_spend_limit_reachedor validation errors.
The error reference 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/accountreturns yourrate_limit_per_minute. - [ ] Batch jobs use a bounded worker pool (at most 4 concurrent live valuations by default) and pace themselves with the
RateLimit-RemainingandRateLimit-Resetheaders. - [ ] Interactive traffic and batch jobs do not compete for the same limits, or batches yield to interactive use.
See rate & concurrency limits and batch valuations.
Timeouts
- [ ] Your HTTP client timeout for
POST /v1/valuationsis 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
statuson every valuation. Onlyvaluedhas 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. - [ ] 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.
- [ ]
notesandattributionsare stored with the result, and anyattribution_textis displayed where the data is shown. See show notes & attributions. - [ ] Test-key results never reach end users. They carry
mode: "test",model.synthetic: trueand asynthetic_resultnote.
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
401or429), you log the Problem'srequest_idtoo. It is the HTTP request ID, also in theX-Request-Idresponse header. A valuation'sval_…ID is in the body'srequest_idand in theX-Valuation-Idheader, never inX-Request-Id. - [ ] Your service checks
GET /v1/accountat 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
failedresults and on anyengine_misconfiguredorinternal_error.
Go-live steps
- Run your integration tests against a test key. See testing.
- Verify your email and check your credit balance under Billing. Contact sales for a credit package if you need more than the signup credits.
- Create a live key with narrow scopes, the countries you serve and a monthly credit limit.
- Deploy the key. Start with a small share of traffic.
- Compare the first live results with your expectations in Request logs. Check precision grades and warnings, not only prices.
- Raise traffic gradually. Contact sales before you need higher rate or concurrency limits.