Rate limits and errors¶

~4 min read · Operations

Error format¶

Errors return a JSON body:

{ "status": "error", "message": "Human-readable summary.", "error": "Detail or code." }

Always read message/error — for a 400, it names the field or rule that failed.

Rejections worth knowing about¶

Two 400s account for most first-run failures, and neither is obvious from the field list.

What you see	What it means
`Cannot read property 'timeRange' of undefined`	A task has no `serviceWindows`. Every task needs at least one — use the vehicle's shift window if the stop is genuinely unconstrained.
Error `10405` — "This trip's pickup window has already passed"	You submitted a window that closed before the current time. The response reports `Current_Time` in HHMM. Date the problem ahead of the clock.

The second one is quiet and expensive: if you build a problem for today out of a full day of stops, every stop earlier than the moment you press send is discarded, and you get back a solution that looks fine but covers a fraction of the work. Anything measured that way is not a real result.

Rate limits (`429`)¶

If you exceed the allowed request rate you'll get a 429. When it happens:

Stop and wait before retrying — back off (e.g. double the delay each time).
Poll less aggressively — a too-tight poll loop is the usual cause.
Spread bursts of submissions out rather than firing them all at once.

Server errors (`5xx`)¶

Transient. Retry with backoff; if a 500 persists for the same payload, capture the request id (if any) and contact DDS Wireless support.

"Successful but empty" — unassigned jobs¶

A 200 with items in unassigned is not an error — the optimization succeeded, but some work couldn't be placed. This is almost always a problem-definition issue, not an API issue. Common reasons:

Reason code	Likely fix
`TIME_WINDOW`	Widen the window, or add capacity/vehicles to reach it in time.
`CAPACITY`	Increase vehicle `capacities`, or split the demand.
`SKILL`	Give a vehicle the required skill, or relax the task's skill.
`NO_VEHICLE` / reachability	Check depot/shift start location and times.

Turn on the diagnostics you need

Set configuration.unassignedTasks: true to get reasons, and statistics: true to see vehicles used vs. unused. They make "why didn't this route the way I expected?" answerable.