V3 is in beta. General availability (GA) is planned for 1 December 2026.
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: retry429, 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 withruns.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:
- The loop polls too fast. A tight loop on
runs.getspends the rate limit on a run that will not finish for ten minutes, and the429it earns then blocks the application’s other calls.waitpolls with a pause that grows from a few seconds to a configurable maximum. - The loop fetches the result too early.
runs.resultbefore the run issucceededis a409.waitonly returns oncestatusis final, soresultis called once. - The loop has no deadline. A run that stays
queuedturnsfailedafter 30 minutes, and a lost worker turns the runfailedwithworker_lost, but a loop without a deadline of its own hangs until then.waittakes a cancellation signal and a maximum interval, and the application sets a deadline fromtime_limit_splus the queue wait it is willing to accept. - The loop treats
failedandcancelledas exceptions. They are final states with a reason inerror, and an application needs to branch on them: resubmit, alert, or fall back to a synchronoussolvewith a smaller budget.waitreturns the final run whatever its status; the application readsstatusand then callsresultor handles the failure.
callback is a 400 with item code not_supported. The pattern, in any language:
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[],retryableandretry_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
waithelper for runs, and nothing that hides a200with unserved tasks.
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.