Skip to main content
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, 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.

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

Retries by endpoint

What may be retried is decided by the HTTP status first, and the full table is on 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: 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 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. 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 codes. 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.

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

What a conforming client looks like

  • One method per row of the methods table, 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, 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.

Before going live

What to prove before production traffic.

SDKs

The TypeScript client, plain HTTP in Python, and generating a client from the spec.

Errors

The error body and every code.

Async runs

Submit, poll, fetch and cancel.