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

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 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.
  • 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 and Handling infeasibility.
  • 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.
  • 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 codes. A client with closed enums fails on the first new value. message texts are never parsed. See 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.
  • 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. The ones that decide architecture:
  • 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.
  • 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 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.

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

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 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.
  • 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.
  • 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.
  • 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_id of 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.