> ## 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.

# Client contract

> The language-independent contract a V3 client implements: one method per endpoint, which calls may be retried and how, the three families of error a client must tell apart, and why a run is waited on rather than polled by hand

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

This page is the specification a client library for the V3 Routing API implements, in any language. It is written so that a team wrapping the HTTP API in their own code, or generating a client from the [OpenAPI document](https://docs.solvice.io/api-reference/solvice-routing-v3.openapi.json), ends up with the same methods, the same retry behaviour and the same error handling as everyone else. The HTTP API is the contract; this page is how to hold it in code.

There is no official SDK for V3 beyond a TypeScript client in beta, and none is planned before V3 reaches general availability on 1 December 2026: a client generated from a schema that may still change in breaking ways would need breaking releases of its own. The `solvice-vrp-solver` packages published on npm and PyPI are clients for the **V2 API**; they send `jobs` and `resources` to `/v2/vrp/...` and cannot send a V3 request. The `@solvice/routing` package on npm is the TypeScript implementation of this contract; install it with the tag, `npm install @solvice/routing@beta`, because the package's `latest` tag points at an older build. See [SDKs](https://docs.solvice.io/guides/platform/sdks.md).

## Methods and endpoints

A client exposes one method per operation, named as below so that code and documentation use the same words. Every method takes the request body of its endpoint and returns the parsed response body, and every method accepts a per-call cancellation signal and extra headers.

| Method | Endpoint | Body | Returns |
| - | - | - | - |
| `solve` | `POST /v3/routing/solve` | `problem`, optional `plan`, optional `options` | The plan: `summary`, `routes`, `plan`, `unassigned` |
| `evaluate` | `POST /v3/routing/evaluate` | `problem`, `plan` | The same shape, scored as given, with violations |
| `suggest` | `POST /v3/routing/suggest` | `problem`, `plan`, optional `options` | `suggestions[]`, one per task outside `plan` |
| `validate.solve` | `POST /v3/routing/validate/solve` | The solve body | `{ "valid": true, "warnings": [] }` |
| `validate.evaluate` | `POST /v3/routing/validate/evaluate` | The evaluate body | The same |
| `validate.suggest` | `POST /v3/routing/validate/suggest` | The suggest body | The same |
| `runs.submit` | `POST /v3/routing/runs` | The solve body | A run with `status: "queued"`, `202` |
| `runs.get` | `GET /v3/routing/runs/{id}` | | The run: `status`, timestamps, `error` when failed |
| `runs.wait` | Repeated `GET /v3/routing/runs/{id}` | | The run once `status` is final. See [Why wait, not get](#why-wait-not-get) |
| `runs.result` | `GET /v3/routing/runs/{id}/result` | | The plan of a `succeeded` run, in the shape `solve` returns |
| `runs.cancel` | `POST /v3/routing/runs/{id}/cancel` | | The run |

Every request carries `Authorization: <api key>` with no `Bearer` prefix, `Content-Type: application/json`, and optionally `Content-Encoding: gzip`. A client sets an `X-Request-Id` on every call when the application does not, logs the `x-request-id` response header, and exposes it on errors. See [Requests](https://docs.solvice.io/api-reference/vrp/v3/introduction.md#requests).

A client does not add behaviour the API does not have. It does not clamp `time_limit_s`, does not default an `objective`, does not drop unknown fields from a request, and does not reorder or rename anything in a response. Where the API returns `400`, the client surfaces the `400`.

### Timeouts

A client sets no fixed HTTP timeout of its own. The application derives one from the request: `options.time_limit_s` plus a margin for the travel lookup and the wait for a solver, which are not counted in the budget. A client may offer a helper that computes that, but it never silently applies one, because a timeout equal to the budget aborts requests that are about to succeed. See [Client timeout](https://docs.solvice.io/guides/vrp/v3/concepts/performance-guide.md#client-timeout).

## Retries by endpoint

What may be retried is decided by the HTTP status first, and the full table is on [Status codes](https://docs.solvice.io/guides/vrp/v3/errors.md#status-codes). A client implements it as: retry `429`, `502` and `503`, waiting the number of seconds in `Retry-After` when the response carries that header and backing off exponentially with jitter otherwise, for a capped number of attempts; retry `500` at most once; never retry `400`, `401`, `403`, `404`, `405`, `409`, `413` or `415`.

Per endpoint, the statuses that can occur and what a retry does:

| Endpoint | Retryable statuses it can return | Repeating the call |
| - | - | - |
| `validate.*`, `evaluate` | `429`, `500`, `503`. The routing service itself never answers `503` here, because no solver slot is taken; a `503` on these endpoints is the platform in front of the solver, in the gateway's own shape, with `Retry-After` but without the error body or a `code`. Never `502`: evaluate estimates travel when the lookup fails | Stateless, safe |
| `solve`, `suggest` | `429`, `500`, `503` in the routing service's own error body, `code` `overloaded` (a full solver queue, with `Retry-After: 1`) or `travel_provider_unavailable` (suspended travel lookups, only with `options.travel_fallback: "fail"`, with `Retry-After` set to the seconds until lookups are tried again, 1 to 5); `502` only with `options.travel_fallback: "fail"` | Stateless, safe. The same body, `seed` and road data give the same plan |
| `runs.submit` | `429` (rate limit, or 10 runs already queued or running: `Retry-After: 30`), `503` (the run could not be started; nothing was created) | **Creates a new run each time it is accepted.** There is no idempotency key, and `X-Request-Id` is a trace id, not a deduplication key: the same body with the same `X-Request-Id` twice is two runs. A client retries `429` and `503`, and never retries a submission whose outcome it does not know without telling the application. An `Idempotency-Key` header for run submission is planned; when it ships a client sends it on every attempt |
| `runs.get`, `runs.result` | `429`, `500`, `503` | Reads, safe. `404` is final: wrong id or another account's run. `409` on `/result` is not an error to retry blindly: `run_not_finished` means poll the status, `no_result` means the run failed or was cancelled |
| `runs.cancel` | `429`, `500`, `503` | Safe to repeat. Cancelling a run that is already final returns `200` with the run unchanged. Cancelling does not stop the worker at once |

A client exposes, on every error, whether the table above calls it retryable and the `Retry-After` value when there was one, so that an application that brings its own retry policy can make the same decision. See [Rate limiting](https://docs.solvice.io/guides/platform/authentication.md#rate-limiting) for the reference retry loop.

## Error families

Three kinds of failure reach a client, with different bodies. A client tells them apart by the HTTP status before it parses anything, and surfaces all three as one error type with the fields below.

| Family | Statuses | Body | What a client exposes |
| - | - | - | - |
| **Gateway** | `401`, `429` on every endpoint; `503` on the validate and evaluate endpoints; `400` (bad `id`), `404`, `409`, `503` on the run endpoints | Not the routing error body: empty, or a gateway shape such as `{"message": "run_not_finished: …", "error": "GATEWAY_ERROR"}` | `status`, the raw body, `Retry-After` when present. On the run endpoints, a `code` read from the start of `message`: `not_found`, `run_not_finished`, `no_result` |
| **Routing service** | `400`, `403`, `413`, `415`, `500` from solve, evaluate, suggest, validate and run submission; `502`, `503` from solve and suggest; `404`, `405` for an unknown path or method under `/v3/` | The [error body](https://docs.solvice.io/guides/vrp/v3/errors.md#the-error-body): `status`, `code`, `message`, `request_id`, and `errors[]` (filled on a `400`, `[]` otherwise) with `code`, `pointer`, `message`, and `limit` and `actual` on `limit_exceeded` | `status`, `code`, `request_id`, the `errors[]` items as data. A client never matches on `message` |
| **Run failure** | HTTP `200` from `runs.get` with `status: "failed"` | A run whose `error` has a `code` (`worker_lost`, `internal`, or the solve error codes) and `message`, and `errors[]` for a plan that could not be driven | Not thrown by `runs.wait`: returned as a final run the application branches on |

Two successful statuses still need reading, and a client leaves that to the application without hiding it: a `200` from solve or evaluate whose `summary.tasks.unassigned_required` is above `0` or whose `summary.score.violation_count` is above `0`, and a `200` from suggest whose task has an empty `insertions` list and a `reason.code`. A client's types make those fields impossible to miss; they do not turn them into exceptions.

Every enumerated response value is an open set: route stop `type` (`routes[].stops[].type`), `category`, `reasons[].constraint`, violation and reason `code`, `termination`, `components` keys, `warnings[].code`, the error `code`s. A client types them as strings with known values, never as closed enums, so that a new value is passed through rather than failed on. Request enums are closed, and so is a plan stop's `type` (in `plan` and in suggest placements), because it feeds a request. See [What your client must do](https://docs.solvice.io/guides/vrp/v3/versioning.md#what-your-client-must-do).

## Why wait, not get

An async run is submitted with `runs.submit`, which answers at once with a `queued` run, and its plan is fetched with `runs.result` once the run has `succeeded`. Between the two, the run is `queued` for the tens of seconds its worker takes to start, then `running` for up to its `time_limit_s`. `runs.get` returns the status at one instant. Applications that call it in a loop get four things wrong often enough that a client provides `runs.wait` and documents `get` as the building block:

1. **The loop polls too fast.** A tight loop on `runs.get` spends the rate limit on a run that will not finish for ten minutes, and the `429` it earns then blocks the application's other calls. `wait` polls with a pause that grows from a few seconds to a configurable maximum.
2. **The loop fetches the result too early.** `runs.result` before the run is `succeeded` is a `409`. `wait` only returns once `status` is final, so `result` is called once.
3. **The loop has no deadline.** A run that stays `queued` turns `failed` after 30 minutes, and a lost worker turns the run `failed` with `worker_lost`, but a loop without a deadline of its own hangs until then. `wait` takes a cancellation signal and a maximum interval, and the application sets a deadline from `time_limit_s` plus the queue wait it is willing to accept.
4. **The loop treats `failed` and `cancelled` as exceptions.** They are final states with a reason in `error`, and an application needs to branch on them: resubmit, alert, or fall back to a synchronous `solve` with a smaller budget. `wait` returns the final run whatever its status; the application reads `status` and then calls `result` or handles the failure.

There is no push alternative today: a body with `callback` is a `400` with item code `not_supported`. The pattern, in any language:

```text theme={null}
run  = runs.submit(body)            -- persist run.id now
run  = runs.wait(run.id, {deadline})
if run.status == "succeeded":  plan = runs.result(run.id)
elif run.status == "failed":   handle(run.error.code, run.error.message)
else:                          handle cancelled
```

Persisting the `id` right after `submit` is part of the contract, because a submission is the one call that is not idempotent: a client that loses the `202` cannot find the run again, and resubmitting creates a second run that counts toward the limit of 10. See [Async runs](https://docs.solvice.io/guides/vrp/v3/runs.md).

## What a conforming client looks like

* One method per row of the [methods table](#methods-and-endpoints), with those names.
* Typed requests that reject unknown fields at compile or construction time where the language allows, because the API rejects them with a `400`.
* Typed responses with open string sets for every enumerated response value, and unknown response fields ignored.
* One error type carrying `status`, `code`, `request_id`, `errors[]`, `retryable` and `retry_after_s`, raised for every non-2xx response, including the gateway's.
* Retries only as in the [table above](#retries-by-endpoint), off by default where the outcome of the previous attempt is unknown, and never on a run submission without the application's consent.
* No timeout, clamp or default the API does not have.
* A `wait` helper for runs, and nothing that hides a `200` with unserved tasks.

A generated client covers the first three. The rest is a thin hand-written layer, and it is the layer this page exists for.

> [card] [Before going live](https://docs.solvice.io/guides/vrp/v3/go-live-checklist.md)
>
> What to prove before production traffic.

> [card] [SDKs](https://docs.solvice.io/guides/platform/sdks.md)
>
> The TypeScript client, plain HTTP in Python, and generating a client from the spec.

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

> [card] [Async runs](https://docs.solvice.io/guides/vrp/v3/runs.md)
>
> Submit, poll, fetch and cancel.


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