V3 is in beta. General availability (GA) is planned for 1 December 2026.
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, so that revoking one does not affect the others and so that production traffic is identifiable. See Authentication.
- The key never reaches a browser or a mobile app. Calls go through your server. See Server-side proxy pattern.
- A
401is 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. - Requests carry an
X-Request-Id. 1 to 128 visible ASCII characters of your choosing; the same value comes back in thex-request-idresponse header, and areq_…id is generated when you send none. Log it with every call. It is a trace id, not an idempotency key: see item 5.
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 a503; 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 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
400is read fromerrors[], not frommessage. Each item has acodeand a JSON Pointer inpointer. Your error handling maps the pointer back to the record that produced the field. See The error body. - You know what validate does not check. It validates
problemandoptions. Two checks need travel times and are made by the real call only: coordinates that span more than one region, and theplan, 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 a400at/planfrom solve. Test warm starts against the real endpoint. - Unknown fields are
400, never ignored. A request that returns200was read exactly as sent. If a field you added had no effect, it was not sent; if it was sent and unknown, you got a400withunknown_field. There is no third case.
3. The response is read, not just received
- A
200with unserved tasks is handled. The plan is a success response whether or not every task is on a route. Readsummary.tasks.unassigned_requiredfirst, thenunassigned[].categoryandreasons[].constraint. Decide, per category, what your application does:impossibleandblockedare input problems,priced_outis working as designed,time_limitwants a bigger budget. See Unassigned jobs and Handling infeasibility. - Priced lateness is read from
lateness_s, not from violations. A window withper_late_hourcan be missed at a cost; that shows aslateness_son the stop and inscore.components.lateness, andviolation_countstays0. A dashboard that only renders violations hides late stops. See 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’stype, inplanand in suggest placements, is closed),category,reasons[].constraint, violation and reasoncode,termination, costcomponentskeys,warnings[].codeand the errorcodes. A client with closed enums fails on the first new value.messagetexts are never parsed. See What your client must do. -
planis 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. - 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 assumesZshifts every arrival.
4. Sized against the limits
The full table is on Limits. The ones that decide architecture:- The HTTP client timeout is derived from
time_limit_s, not fixed.time_limit_sbounds 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. - 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. - A rate-limited
429is handled as a gateway response. It carries no routing error body; branch on the status, readRetry-Afterwhen present, back off otherwise. See 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. Run submission is the one call where a retry creates a second run, so persist theid from the 202 first.
- A retry loop has a cap and backoff with jitter. Three attempts with
Retry-Afteror exponential backoff is the pattern on Authentication. - A run that ends
failedorcancelledis a handled state./resultanswers409withno_resultfor both; the reason is in the run’serror. A client that only knowssucceededhangs on the others. - There is no callback. A body with
callbackis a400with item codenot_supported. Polling is the mechanism; see 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. The ones that cost the most when skipped:- Coordinates are
[longitude, latitude]. A swapped pair lands in another region, so the usual outcome is a400at/problem/locationsbecause 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 withunreachable. 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,serviceDurationand every other undefined key are a400withunknown_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.
- 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/evaluateon the operation’s actual sequence to get it scored on the same objective. See Evaluate. - Confirm the prices. An omitted
objectiveis priced at the V3 defaults, 35 per route hour and 0.20 per kilometre, in no particular currency. Setobjective.costsandobjective.currencyto yours before any plan is compared with another. See 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.
- Know how to reach support. Keep the
request_idof any failing call; it is the first thing support asks for.
Client contract
What any client, in any language, must do per endpoint.
Integration paths
The reading order for your mission, with the pitfall at each step.
Limits
Every size, time and value limit, and the error each produces.
Errors
The error body, every code, and what to retry.