Errors - Solvice Docs

V3 is in beta. General availability (GA) is planned for January 2027.

Overview

There are two kinds of “it didn’t work” on the V3 Routing API, and they look different:

The request failed. You get a 4xx or 5xx status and an error body. Nothing was planned.
The request succeeded but not every job was planned. You get a 200. summary.tasks.unassigned is above 0, and unassigned[] says which jobs were left out and why. See Unassigned jobs.

Got a 401 or a 429? Those come from the API gateway, before the request reaches the routing service, and do not use the error body below. See Authentication errors and 429 Too Many Requests.

The error body

Every error the routing service returns from /v3/routing/solve, /v3/routing/evaluate and /v3/routing/suggest has this JSON body. That covers the statuses 400, 403, 413, 415, 500, 502 and 503:

400 Bad Request

{
  "status": "BAD_REQUEST",
  "code": "invalid_request",
  "message": "2 problems in request",
  "request_id": "req_7f3a2c90d1e4b5a6",
  "errors": [
    {
      "code": "limit_exceeded",
      "pointer": "/options/time_limit_s",
      "message": "options.time_limit_s must be <= 60, got 600",
      "limit": 60,
      "actual": 600
    },
    {
      "code": "out_of_range",
      "pointer": "/problem/jobs/1/priority",
      "message": "job 'delivery-2': priority must be >= 1, got 0"
    }
  ]
}

string

The HTTP status as text: BAD_REQUEST, FORBIDDEN, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, INTERNAL_SERVER_ERROR, BAD_GATEWAY or SERVICE_UNAVAILABLE.

string

What kind of failure this is. One value per HTTP status; see the table below. Branch on this.

string

A summary for people. With one item in errors[] it is that item’s message; with several it is the count, as above.

string

Identifies this request. The same value is returned in the x-request-id response header. Quote it when you contact support.

array

One entry per problem found in the request. Present on a 400; absent on other statuses.

string

What is wrong with this field. See Item codes.

string

A JSON Pointer (RFC 6901) to the offending place in the request body. Absent when the problem has no location, such as a body that is not JSON or a query parameter, which the message names. See Pointers.

string

A description for people. Do not parse it; branch on code and pointer.

integer

On limit_exceeded only: the cap.

integer

On limit_exceeded only: the count your request has. For options.time_limit_s it is the value you sent, rounded up to whole seconds.

Pointers

A pointer is a path from the root of the body you sent. Array elements are addressed by index.

Pointer	Points at
`/problem/jobs/1/priority`	`priority` of the second job
`/problem/vehicles/0/shifts/0/from`	`from` of the first shift of the first vehicle
`/problem/relations/2`	The third relation
`/plan/routes/0/stops/3`	The fourth stop of the first plan route
`/options/time_limit_s`	`time_limit_s` in `options`

For an unknown field the pointer usually ends at the unknown key. Inside a job, a shipment, a break or a relation it can stop at the enclosing object, such as /problem/jobs/0; the message always names the field. For a missing field the pointer names the object that lacks the field, and the message names the field. An unknown query parameter has no pointer; the message names it. A problem that is only found after travel times are fetched can carry a less precise pointer: it can name a whole collection, or be absent. One case points at a key that does not exist in the request: when the coordinates span more than one region, the pointer is /problem/locations. The coordinates to check are the ones on your jobs, shipments and depots, and on the start and end of each shift.

Pointers, fields and reasons

Three response fields tell you where to look. The first two are JSON Pointers.

Field	Appears in	What it is
`errors[].pointer`	A `400` error body	A JSON Pointer from the root of the request body, so it names `problem`, `plan` or `options` first. It addresses array elements by index
`unassigned[].relaxations[].pointer`	A `200` from solve or evaluate	A JSON Pointer from the root of the request body to the field to change: `/problem/jobs/<i>/pickup_load` (`/delivery_load` when the job only delivers) or `/problem/jobs/<i>/time_windows` for a job, `/problem/shipments/<i>/load` or `/problem/shipments/<i>/pickup/time_windows` for a shipment
`suggestions[].reason`	A `200` from suggest	`{ code, message }`, present when a task has no insertions. Branch on `code`, show `message`. See When a task gets no insertions

How many problems are reported

A body that cannot be read at all (bad JSON, unknown field, missing field, wrong type) reports the first problem only. Fix it and resend.
Once the body reads cleanly, validation reports the problems it finds together, up to 100 items. It may list only the first problem of each job, shipment, vehicle or depot, and it checks what ties entries together (vehicle references, relations, quotas, the objective) only once every entry is valid on its own. A corrected request can therefore show new problems: fix and resend until it passes.
A problem with the plan, which is matched to the problem only after travel times are fetched, is reported on its own, one at a time.

Status codes

HTTP	`code`	Meaning	Retry?
`400`	`invalid_request`	The request is invalid. `errors[]` lists each problem	No. Fix the request
`401`	n/a	The API key is missing or not accepted. Sent by the gateway with a different body	No. Fix the key
`403`	`feature_not_enabled`	The request uses a feature your account does not have. Today that is `travel.engine: "tomtom_real_time"`. The key itself is fine	No. Remove the feature or contact Solvice
`413`	`payload_too_large`	The body is larger than 10 MiB after decompression	No. Send a smaller problem
`415`	`unsupported_media_type`	`Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or `Content-Encoding` is something other than `gzip`	No. Fix the headers
`429`	n/a	You are over the rate limit. Sent by the gateway, not in the error body	Yes, with backoff
`500`	`internal`	A fault on the server side	Once, then contact support with the `request_id`
`502`	`travel_provider_error`	Travel times and distances could not be fetched (on solve and suggest only with `travel_fallback: "fail"`)	Yes, with backoff
`503`	`overloaded`	No capacity right now, or the travel-time service is temporarily cut off (on solve and suggest only with `travel_fallback: "fail"`)	Yes, after the `Retry-After` header (always 1 second), with backoff if it repeats

Branch on the HTTP status first, then on code. Read code only on a status that has one in this table.

400 Bad Request

Unknown fields are a 400, never ignored. So are a misspelled field, a wrong type and a field the API does not support yet. A request that returns 200 was read exactly as you sent it.

400: unknown field

{
  "status": "BAD_REQUEST",
  "code": "invalid_request",
  "message": "unknown field `time_limit`, expected one of `time_limit_s`, `seed`, `polyline`, `travel_fallback` at line 1 column 688",
  "request_id": "req_2b9d41c07a35e6f8",
  "errors": [
    {
      "code": "unknown_field",
      "pointer": "/options/time_limit",
      "message": "unknown field `time_limit`, expected one of `time_limit_s`, `seed`, `polyline`, `travel_fallback` at line 1 column 688"
    }
  ]
}

To check a request without running it, send it to POST /v3/routing/validate/solve, /v3/routing/validate/evaluate or /v3/routing/validate/suggest, the one that matches the endpoint. You get 200 {"valid": true, "warnings": []} or the same 400 the real call would return (or its 403, for a feature your account does not have), with no travel-time fetch and no search. It validates problem and options. Coordinates that span more than one region and the plan (its references and whether it imports, warm-start plan on solve included) are checked only by the real call, after the travel-time fetch; suggest’s own check that plan leaves a task to place does run here. The body is checked as the chosen endpoint checks its own, so a field that endpoint does not take, such as options on evaluate, is the same unknown_field 400. The validate endpoints take no query parameter, and neither do solve, evaluate and suggest. Any query parameter, including a misspelt name or the removed validate_only, is a 400 with the error body above and an item of code unknown_field; query items carry no pointer, the parameter is named in message.

413 and 415

The 10 MiB limit applies to the body after gzip decompression. To send a compressed body, set Content-Encoding: gzip and keep Content-Type: application/json. See Limits.

502 Bad Gateway

The solver could not get travel times for your locations from the routing data provider. The request itself may be fine. Retry with backoff; if it keeps failing for the same request, contact support with the request_id. Only a solve or a suggest returns this error, and only with options.travel_fallback: "fail". By default, travel times that cannot be fetched, for any reason, are estimated: /v3/routing/solve plans on the estimate and summary.travel_estimated says so; /v3/routing/suggest ranks on it and sets travel_estimated. options.travel_fallback takes "estimate" (the default) or "fail", which returns the 502 or 503 instead. /v3/routing/evaluate has no such option and always estimates, setting summary.travel_estimated. See Distance matrices. Coordinates that span more than one region or continent are a different case: that is a 400 with item code invalid_value, and usually means a coordinate is in [latitude, longitude] order. V3 coordinates are [longitude, latitude]. See Distance matrices for how travel data is fetched.

429 Too Many Requests

Requests are rate limited by the API gateway. A request over the limit is rejected with 429 before it reaches the routing service, so its body is not the error body on this page: detect it from the HTTP status and do not read code or request_id from it. Back off and retry. See Authentication. POST /v3/routing/runs also answers 429, with Retry-After: 30, while 10 runs of your account are queued or running: see Async runs.

503 Service Unavailable

The service is at capacity, or, on a solve or suggest with travel_fallback: "fail", travel-time lookups are temporarily suspended after repeated failures. Every 503 carries a Retry-After header, always 1 second. It is a floor, not a forecast: wait that long and retry, and add backoff if it repeats.

503 Service Unavailable

{
  "status": "SERVICE_UNAVAILABLE",
  "code": "overloaded",
  "message": "All solver slots are busy, try again later",
  "request_id": "req_91c4e02f6b7d3a58"
}

Item codes

errors[].code on a 400. New values can be added, so handle a value you do not recognise as a generic invalid request.

`errors[].code`	Meaning	Typical cause
`invalid_json`	The body is not valid JSON	Trailing comma, unquoted key, truncated body
`invalid_type`	A value has the wrong JSON type, or is not one of the allowed values	A string where a number is expected; an unknown relation `type`; a skill sent as `"fridge"` rather than `{ "name": "fridge" }`
`unknown_field`	A field the schema does not define	A typo, a camelCase name, a V2 field
`missing_field`	A required field is absent	A job, vehicle or shift without `id`; a shift without `from` or `to`
`invalid_value`	A value is well-formed but not acceptable	A shift id that is empty or too long; a misplaced `reload` stop in `plan`
`not_supported`	A field or value that exists in the schema but is not available yet	a relation that names a shipment id; a `location` on a windowed break
`out_of_range`	A number outside its allowed range	A negative `drop_cost`; `priority: 0`; a negative `max_overtime_s`; a negative `time_limit_s` (a value below `0.1` is raised to 100 ms, not rejected)
`duplicate_id`	An id used twice where ids must be unique	Two vehicles with the same `id`; a stop listed twice in `plan`
`unknown_reference`	A reference to an id that does not exist	A depot, vehicle, job or shift id that is not in `problem`
`conflicting_fields`	Two fields that cannot be combined, or one that needs another	`drop_cost` with `priority`
`limit_exceeded`	A count over a published limit. Carries `limit` and `actual`	More than 10,000 tasks, or more than 400 on solve; `time_limit_s` above 60. See Limits

Authentication errors

A request with a missing or unrecognised key is rejected by the API gateway with 401 before it reaches the solver. The body is not the error body above, and comes in two shapes:

{
  "message": "Invalid authentication token",
  "error": "GATEWAY_ERROR"
}

(empty body)

Detect it from the HTTP status, and do not parse the body as JSON without checking it is non-empty. The header is Authorization: YOUR_API_KEY, with no Bearer prefix. See Authentication.

Unassigned jobs

A 200 from /v3/routing/solve does not mean every job was planned. Check summary.tasks:

Field	Meaning
`served`	Jobs and shipments on a route
`unassigned`	Jobs and shipments on no route: the length of `unassigned[]`
`unassigned_required`	The unassigned ones that carry no `drop_cost`

A job is one task and a shipment is one task. Every task is on a route when unassigned is 0; none is when served is 0. This section is the reference for each category and reason code. For the order to read them in, how to confirm a diagnosis with /v3/routing/evaluate and /v3/routing/suggest, and the ranked fixes, see Handling infeasibility. The plan the solver returns never breaks a hard constraint. A job that cannot be served within the rules is left out and reported, with a reason:

{
  "unassigned": [
    {
      "task": "delivery-7",
      "category": "blocked",
      "reasons": [
        { "constraint": "time_window",
          "message": "A route cannot reach this task within its time window"
        }
      ],
      "relaxations": [
        {
          "pointer": "/problem/jobs/6/time_windows",
          "op": "extend_time_window",
          "amount": 900,
          "unit": "s",
          "message": "Extend a time window by 900s (~15 min)."
        }
      ]
    }
  ]
}

string

The job id, or the shipment id for a shipment. A shipment is listed once, not once per stop.

string

What kind of fix can work. One of the four values in Categories. Always present.

array

Never empty. Each reason names the constraint that kept the task out on at least one vehicle and carries a message for people. A task lists each constraint once. For priced_out and time_limit no rule did, so there is one reason without a constraint. See Reasons.

array

A best-effort hint at the smallest change that would let the task fit. Empty when no simple change exists, such as for a skills mismatch.

Each relaxation has an op, an amount in unit, a message sentence and a pointer:

`op`	`unit`	Meaning
`reduce_load`	`load`	Lower the task’s demand by `amount`, or add that much capacity to a vehicle that can serve it
`extend_time_window`	`s`	Widen a time window by `amount` seconds

pointer is a JSON Pointer into the request body, as in /problem/jobs/6/time_windows for the seventh job. A shipment is under /problem/shipments/, as in /problem/shipments/0/load. See Pointers, fields and reasons.

`category`	Meaning	What to do
`impossible`	No vehicle can ever serve this job, whatever the other jobs do	Fix the input: skills, tags, eligibility, a time window no shift overlaps, or a load no vehicle can carry
`blocked`	Some vehicle could serve it alone, but not alongside the jobs that are planned, or its all-or-none crew cannot be placed together	Add capacity or working time, widen windows, or accept that it does not fit. More solve time alone is unlikely to help
`priced_out`	The job has a `drop_cost`, a slot for it exists, and serving it there costs at least the fee	Working as designed. Raise the `drop_cost` if it should be served. More solve time does not help
`time_limit`	A feasible slot exists and the search did not use it in its time budget	Raise `options.time_limit_s`

Reasons

Each reason names one constraint that refused the task, in the same vocabulary as evaluate’s violation codes, and carries a message for people. There is no separate outcome code: category says what kind of fix can work, and constraint says which rule refused the task. A priced_out or time_limit task has one reason with no constraint. A task lists each constraint once, unreachable first, so a task refused for capacity on one vehicle and for its time window on another has two reasons, capacity and time_window. Treat a constraint you do not recognise as unknown.

`reasons[].constraint`	Meaning	What to check
`unreachable`	There is no road connection to or from the location	The coordinate: `[longitude, latitude]` order, on land, near a road
`max_leg_travel`	Every way to reach or leave the task needs a leg longer than a vehicle’s `limits.max_leg_travel_s`	The leg cap on the vehicles that could serve it
`required_skills`	No vehicle provides the required skills	`skills[].name` spelling and `min_level` on job and vehicle
`serves_tags`	No shift serves any of the job’s tags	`jobs[].tags` against `shifts[].serves_tags`
`capacity`	No vehicle has enough capacity, or the ones that do are full	`pickup_load`, `delivery_load` and `vehicles[].capacity`
`time_window`	The time window cannot be met by any route	`time_windows` against shift hours and travel time
`eligible_vehicles`	The allowed and excluded lists rule out the vehicle	`eligible_vehicles`
`shift_end`	Serving it would end a route after its shift, also for a task with no time windows that does not fit in the shift	Shift hours and `max_overtime_s`
`max_distance`, `max_route_duration`, `max_stops`	Serving it would exceed that limit	`vehicles[].limits`
`period_limit`, `quota`	Serving it would exceed a `limits.periods[]` or `quotas[]` cap, given what the other shifts already use	`vehicles[].limits.periods`, `quotas`
`same_vehicle`, `same_day`, `same_route`, `compatible_vehicles`	A relation ties the task to a vehicle, day or route that cannot take it	The task’s relations
`all_or_none`	The task fits, but another member of its `all_or_none` group cannot be served; the category is that member’s	That member’s reasons
`synchronized`, `time_lag`	Each member of an all-or-none crew fits alone, but the crew cannot be placed together; the category is `blocked`	The members’ shifts, windows and eligible vehicles overlap
`sequence`, `tag_order`, `shipment`, `break`, `multi_trip`	That rule refused every position; a one-member `sequence` pins its task first on the route	The rule on the task or the vehicle
`unknown`	The solver recorded no specific rule	Each rule on the job against each vehicle that could serve it

The Constraints page lists which rule produces which constraint.

On evaluate

/v3/routing/evaluate does not search, so unassigned[] and the score mean something different there:

summary.score.violation_count counts the rules your plan breaks; 0 means none. It says nothing about tasks the plan leaves out. Broken rules are reported as violations.
unassigned[] lists every task that is in no route of your plan, in the same shape as above. The category then describes whether the task could be added to the plan as it stands:

`category` on evaluate	Meaning
`impossible`	No vehicle can serve the task at all, or one of its `all_or_none` partners
`blocked`	Some vehicle could serve it alone, but it does not fit into the plan you sent, or one of its `all_or_none` partners does not, or its all-or-none crew cannot be placed together
`priced_out`	It fits into the plan, it has a `drop_cost`, and serving it at the cheapest position costs at least the fee
`time_limit`	It fits into the plan you sent. It is unassigned only because your plan does not include it

A task that fits comes back with one reason and no constraint, unless its all_or_none group holds it back (all_or_none) or its all-or-none crew cannot be placed together (synchronized, time_lag). Evaluate has no time budget and takes no options, so there is nothing to raise: add the task to plan, or ask /v3/routing/suggest where it fits best.

Troubleshooting

I get a 400 for a field that used to work in V2

V3 uses snake_case names and a different structure, and rejects every field it does not define. The pointer shows which field. See Migration from V2 for the mapping.

Every job comes back unassigned

Look at category and reasons[].constraint on a few of them. time_window with category impossible on all of them usually means the job windows and the shifts are on different dates or in different time zones. unreachable on all of them usually means coordinates are in [latitude, longitude] order.

A job is unassigned with time_limit

On solve, the default options.time_limit_s is 150 ms plus 4 ms per task. Larger problems may need more: raise it, up to 60. On evaluate, time_limit means the task fits but is not in your plan: see On evaluate.

Suggest returns no insertions for a task

The entry carries a reason whose code says why: only infeasible is final, while time_limit and candidates_exhausted can change with a larger options.time_limit_s or options.max_insertions. For a crew, candidates_exhausted does not change with either; /v3/routing/solve may still place it. See When a task gets no insertions.

Solve rejects my warm-start plan with a 400

A stop inside a route’s locked_count cannot be dropped, so if it breaks a hard rule the request fails. errors[] lists each such stop (up to 100), each with the pointer of its stop (/plan/routes/{i}/stops/{k}) and the rule in the request’s terms, such as time window or shift end, capacity or eligible_vehicles; /v3/routing/validate/solve returns 200 for those cases. On /v3/routing/runs the run ends failed instead. A stop marked pinned: true outside a locked_count prefix (a shipment leg whose other leg is inside counts as inside) never fails the request: one that cannot be served on its vehicle comes back in unassigned[] with the rule that refuses it. Send the same problem and plan to /v3/routing/evaluate: it scores the plan as it is and lists each rule it breaks, stop by stop.

I get a 415 although I send JSON

The Content-Type header must be application/json. Some HTTP clients send text/plain or a form type unless told otherwise. If you compress the body, the only accepted Content-Encoding is gzip.

I want to check requests in CI without being billed

Send it to POST /v3/routing/validate/solve, /v3/routing/validate/evaluate or /v3/routing/validate/suggest. The request goes through the same validation as a real call and returns before any travel-time fetch or search.

Limits

Request limits and what you get when you exceed one.

Authentication

API keys, the 401 response and rate limiting.

Evaluate

See exactly which rules a plan breaks.

API reference

Request and response schema for every endpoint.