Skip to main content

Route Planning error codes

Stable codes returned in JSON error responses as errorCode (HTTP status varies).

{
  "success": false,
  "errorCode": "RP_INGEST_003",
  "message": "Human-readable detail"
}

Full reference in the TCMS repo: docs/developer/route-planning/ERROR_CODES.md.

Ingest and upload​

CodeHTTPMeaning
RP_INGEST_001401Webhook authentication failed
RP_INGEST_002409Duplicate X-Idempotency-Key
RP_INGEST_003400Invalid webhook payload or upload parse error
RP_UPLOAD_001400/500Excel/CSV upload failed

Session​

CodeHTTPMeaning
RP_SESSION_001409Invalid session status transition
RP_SESSION_002404/500Session not found or update failed

PUT /sessions/{id} — status field​

Optional "status" in the request body advances the session when the transition is allowed (same rules as RoutePlanningSessionTransitionValidator).

Set automatically by server:

  • POST …/optimize → OPTIMIZING, then OPTIMIZED or OPTIMIZATION_FAILED
  • POST …/commit-to-planner → COMMITTED on success

Set by wizard via PUT:

  • Browser HERE optimize lifecycle
  • Assign to planner after legacy planner save (browser-optimized routes)

Integrators must chain valid transitions; skipping steps returns RP_SESSION_001.

Optimization​

CodeHTTPMeaning
RP_OPT_004503HERE API key not configured on server
RP_EXPORT_003409Session not optimized (export / assignment payload)

Assign to planner (commit)​

CodeHTTPMeaning
RP_COMMIT_001400/500Planner trip creation failed
RP_COMMIT_002409Session not OPTIMIZED — run optimization first
RP_COMMIT_003404No optimized routes on server for commit
RP_COMMIT_004400Missing truck assignment for a route
RP_COMMIT_005400Missing driver (name or IC) for a route
RP_COMMIT_007409Partial commit — some routes skipped
RP_COMMIT_008409Session already COMMITTED — duplicate assign blocked

POST /sessions/{id}/commit-to-planner​

Creates one Planner trip per optimized route using PlannerService.savePlan. Requires server-stored optimization result and status OPTIMIZED.

When routes exist only in the browser HERE snapshot, the wizard uses the legacy planner save API and advances status to COMMITTED via PUT /sessions/{id} — operators still use Assign to planner only.

Dispatch​

CodeHTTPMeaning
RP_DISPATCH_006400Invalid callback URL (non-HTTPS, private IP, etc.)

Retry​

CodeHTTPMeaning
RP_RETRY_001409Retry not allowed for current session state

Use POST …/optimize/retry only when status is OPTIMIZATION_FAILED.

Live tracking​

CodeHTTPMeaning
RP_TRACK_001500Live routes or GPS trail query failed
RP_TRACK_002404 / 400Route not found, invalid route id, or session not optimized/committed/exported

See Live route tracking API.

Health​

CodeHTTPMeaning
RP_HEALTH_001503Route planning DB migration missing
RP_HEALTH_002503HERE API key not configured