> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Before going live

> A checklist for the week before a V3 integration carries production traffic: what to prove with the unbilled validate endpoints, what to size against the limits, how retries and repeated submissions behave, and the rules an agent that writes requests must follow

> [!NOTE]
>
> **V3 is in beta.** General availability (GA) is planned for 1 December 2026.

There is no separate sandbox host. `https://api.solvice.io` is the only host, and the V3 endpoints on it are the production endpoints from the first call. What stands in for a sandbox is a set of unbilled check endpoints, `POST /v3/routing/validate/solve`, `/v3/routing/validate/evaluate` and `/v3/routing/validate/suggest`, and the practice of giving each of your environments its own API key. This page is the list of things to have proven before real orders depend on the answers.

Each item names the page that explains it. Work through the list in order; the early items catch the mistakes that make the later ones meaningless.

## 1. Keys and environments

* [ ] **One key per environment.** Create separate keys for development, staging and production on [platform.solvice.io](https://platform.solvice.io), so that revoking one does not affect the others and so that production traffic is identifiable. See [Authentication](https://docs.solvice.io/guides/platform/authentication.md).
* [ ] **The key never reaches a browser or a mobile app.** Calls go through your server. See [Server-side proxy pattern](https://docs.solvice.io/guides/platform/authentication.md#server-side-proxy-pattern).
* [ ] **A `401` is handled before JSON is parsed.** It comes from the gateway, with an empty body or one that is not the routing error body. Branch on the HTTP status first. See [Authentication errors](https://docs.solvice.io/guides/vrp/v3/errors.md#authentication-errors).
* [ ] **Requests carry an `X-Request-Id`.** 1 to 128 visible ASCII characters of your choosing; the same value comes back in the `x-request-id` response header, and a `req_…` id is generated when you send none. Log it with every call. It is a trace id, not an idempotency key: see [item 5](#5-retries-timeouts-and-repeated-submissions).

## 2. Every request shape passes validate

The validate endpoints parse and check a body exactly as the real endpoint does, fetch no travel times, run no search, take no solver slot, and are not billed. The routing service never answers a validate call with a `503`; one that does arrive comes from the platform in front of the solver, in the gateway's own shape with `Retry-After` and without the error body, and is retried like any other `503`. A valid request answers `200 {"valid": true, "warnings": []}`; an invalid one answers the same `400` or `403` the real call would. See [Dry run](https://docs.solvice.io/api-reference/vrp/v3/introduction.md) in the API reference.

* [ ] **Every request your code can produce has been sent to the matching validate endpoint.** Not one sample: one per code path. A field that only appears when a customer sets an option is the one that fails first in production. Run this in CI against recorded fixtures.
* [ ] **A `400` is read from `errors[]`, not from `message`.** Each item has a `code` and a JSON Pointer in `pointer`. Your error handling maps the pointer back to the record that produced the field. See [The error body](https://docs.solvice.io/guides/vrp/v3/errors.md#the-error-body).
* [ ] **You know what validate does not check.** It validates `problem` and `options`. Two checks need travel times and are made by the real call only: coordinates that span more than one region, and the `plan`, whether it names the problem's vehicles, shifts, tasks and depots and whether it can be imported. A request that passes validate can still get a `400` at `/plan` from solve. Test warm starts against the real endpoint.
* [ ] **Unknown fields are `400`, never ignored.** A request that returns `200` was read exactly as sent. If a field you added had no effect, it was not sent; if it was sent and unknown, you got a `400` with `unknown_field`. There is no third case.

## 3. The response is read, not just received

* [ ] **A `200` with unserved tasks is handled.** The plan is a success response whether or not every task is on a route. Read `summary.tasks.unassigned_required` first, then `unassigned[].category` and `reasons[].constraint`. Decide, per category, what your application does: `impossible` and `blocked` are input problems, `priced_out` is working as designed, `time_limit` wants a bigger budget. See [Unassigned jobs](https://docs.solvice.io/guides/vrp/v3/errors.md#unassigned-jobs) and [Handling infeasibility](https://docs.solvice.io/guides/vrp/v3/infeasibility.md).
* [ ] **Priced lateness is read from `lateness_s`, not from violations.** A window with `per_late_hour` can be missed at a cost; that shows as `lateness_s` on the stop and in `score.components.lateness`, and `violation_count` stays `0`. A dashboard that only renders violations hides late stops. See [Time windows](https://docs.solvice.io/guides/vrp/v3/constraints.md#time-windows).
* [ ] **Unknown values are accepted everywhere the contract says so.** New values can appear in route stop `type` (`routes[].stops[].type`; a plan stop's `type`, in `plan` and in suggest placements, is closed), `category`, `reasons[].constraint`, violation and reason `code`, `termination`, cost `components` keys, `warnings[].code` and the error `code`s. A client with closed enums fails on the first new value. `message` texts are never parsed. See [What your client must do](https://docs.solvice.io/guides/vrp/v3/versioning.md#what-your-client-must-do).
* [ ] **`plan` is stored.** It is the state of the day in request shape, and the only thing you can send back to re-plan, evaluate a manual change or ask for insertions. The API keeps none of it after the response. See [Re-optimization](https://docs.solvice.io/guides/vrp/v3/reoptimization.md).
* [ ] **Times are read in the offset they carry.** Response times are written in the offset of the shift's `from`, not in UTC. A parser that assumes `Z` shifts every arrival.

## 4. Sized against the limits

The full table is on [Limits](https://docs.solvice.io/guides/vrp/v3/limits.md). The ones that decide architecture:

| Decide | Limit | Consequence |
| - | - | - |
| Synchronous solve or an async run | `POST /v3/routing/solve` takes at most 400 tasks and a `time_limit_s` of at most 60. A run takes 10,000 tasks and 3,600 s | Above either, use `POST /v3/routing/runs` with the same body. The switch is a different call pattern, not a flag; build it before you need it |
| Concurrent runs | 10 queued or running runs per account. The eleventh submission is a `429` with `Retry-After: 30`. A cancelled run keeps counting until its worker stops | A batch job that submits 50 runs at once needs a queue of its own in front of the API |
| How long a run may take | A run that is still `queued` after 30 minutes turns `failed` with `error.code` `internal`; one whose worker is lost turns `failed` with `worker_lost` | Treat `failed` as a state to handle, not an exception to log |
| How long a result is kept | 365 days after the run is final, in `expires_at` | Fetch and store the plan; do not treat the API as the archive |
| Body size | 10 MiB after decompression; gzip accepted | Gzip large problems. Above 10 MiB, split the problem |
| Dimensions, skills, tags, eligibility | 4 capacity dimensions; 256 distinct skill combinations, tag values and eligibility sets | A misspelt dimension name counts as a dimension. Normalise names before sending |

* [ ] **The HTTP client timeout is derived from `time_limit_s`, not fixed.** `time_limit_s` bounds building the first plan and the search only; the travel lookup and any wait for a free solver come on top. A timeout equal to the budget aborts solves that are about to return. See [Client timeout](https://docs.solvice.io/guides/vrp/v3/concepts/performance-guide.md#client-timeout).
* [ ] **The budget was chosen from `search_progress`, not guessed.** The default is 150 ms plus 4 ms per task, which is a floor for a first answer, not a recommendation. See [See how fast the search converges](https://docs.solvice.io/guides/vrp/v3/concepts/performance-guide.md#see-how-fast-the-search-converges).
* [ ] **A rate-limited `429` is handled as a gateway response.** It carries no routing error body; branch on the status, read `Retry-After` when present, back off otherwise. See [429 Too Many Requests](https://docs.solvice.io/guides/vrp/v3/errors.md#429-too-many-requests).

## 5. Retries, timeouts and repeated submissions

What may be retried, by status and by endpoint, is one table: [Retries by endpoint](https://docs.solvice.io/guides/vrp/v3/client-contract.md#retries-by-endpoint). Run submission is the one call where a retry creates a second run, so persist the `id` from the `202` first.

* [ ] **A retry loop has a cap and backoff with jitter.** Three attempts with `Retry-After` or exponential backoff is the pattern on [Authentication](https://docs.solvice.io/guides/platform/authentication.md#rate-limiting).
* [ ] **A run that ends `failed` or `cancelled` is a handled state.** `/result` answers `409` with `no_result` for both; the reason is in the run's `error`. A client that only knows `succeeded` hangs on the others.
* [ ] **There is no callback.** A body with `callback` is a `400` with item code `not_supported`. Polling is the mechanism; see [Why wait, not get](https://docs.solvice.io/guides/vrp/v3/client-contract.md#why-wait-not-get).

## 6. The requests an agent writes

If an AI agent builds requests from a description of the operation, it follows the rules in [AI agents](https://docs.solvice.io/guides/vrp/v3/ai-agents.md). The ones that cost the most when skipped:

* [ ] **Coordinates are `[longitude, latitude]`.** A swapped pair lands in another region, so the usual outcome is a `400` at `/problem/locations` because the request then spans more than one region. Only a swapped pair that stays inside the matrix region gets through, and then every task that depends on it is unassigned with `unreachable`. A plausible wrong coordinate gives no error at all, so coordinates are never rounded or invented.
* [ ] **Field names come from the reference, never from another API.** `time_limit`, `timeWindows`, `serviceDuration` and every other undefined key are a `400` with `unknown_field`. The agent sends the request to the validate endpoint before the real one.
* [ ] **Windows are hard unless priced.** When every task is unassigned with category `impossible`, the windows and the shifts are usually on different dates or UTC offsets.
* [ ] **Nothing is defaulted that the operation did not state.** No invented capacity, no assumed service time, no rule the customer did not give. The agent asks on irreducible ambiguity and reports what it could not model instead of approximating it. See [What never to default](https://docs.solvice.io/guides/vrp/v3/ai-agents.md).
* [ ] **A `relaxations[]` entry is surfaced, not applied.** Widening a window or reducing a load changes the customer's rule. The decision is the customer's.

## 7. The last week

* [ ] **Replay a week of real demand through validate, then through solve with your production budget,** and read the unassigned categories per day. A category that appears in replay appears in production.
* [ ] **Compare a day's plan with what the operation did,** using `/v3/routing/evaluate` on the operation's actual sequence to get it scored on the same objective. See [Evaluate](https://docs.solvice.io/guides/vrp/v3/evaluate.md).
* [ ] **Confirm the prices.** An omitted `objective` is priced at the V3 defaults, 35 per route hour and 0.20 per kilometre, in no particular currency. Set `objective.costs` and `objective.currency` to yours before any plan is compared with another. See [The V3 defaults](https://docs.solvice.io/guides/vrp/v3/concepts/scoring-explanation.md#if-you-set-nothing-the-v3-defaults).
* [ ] **Know what beta means for you.** V3 is in beta until 1 December 2026 and can change in breaking ways until then. After that date, breaking changes ship only in a new major. See [Versioning](https://docs.solvice.io/guides/vrp/v3/versioning.md).
* [ ] **Know how to reach support.** Keep the `request_id` of any failing call; it is the first thing support asks for.

> [card] [Client contract](https://docs.solvice.io/guides/vrp/v3/client-contract.md)
>
> What any client, in any language, must do per endpoint.

> [card] [Integration paths](https://docs.solvice.io/guides/vrp/v3/integration-paths.md)
>
> The reading order for your mission, with the pitfall at each step.

> [card] [Limits](https://docs.solvice.io/guides/vrp/v3/limits.md)
>
> Every size, time and value limit, and the error each produces.

> [card] [Errors](https://docs.solvice.io/guides/vrp/v3/errors.md)
>
> The error body, every code, and what to retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.