Errors

Every code this platform can return, generated from the code that defines them.

Write your branching logic against `code`, which is never translated. Do not branch on `message`: it is translated, and its wording changes with the caller's language.

{
  "request_id": "req_01J8Q…",
  "error": {
    "code": "CAPABILITY_NOT_ENABLED",
    "message": "…",
    "status": 403,
    "capability": "routing.optimize",
    "retry_after_seconds": null,
    "details": [{"field": "jobs[3].location.lat", "code": "OUT_OF_RANGE", "message": "…"}],
    "doc_url": "…/developer/errors"
  }
}

The four ways a call can be refused are deliberately distinguishable without reading text: NOT_AUTHORIZED means this operation is not allowed for this credential; CAPABILITY_NOT_ENABLED means the account has not subscribed; CAPABILITY_NOT_GRANTED_TO_KEY means the account has it but this key does not; and QUOTA_EXHAUSTED answers 402 rather than 403 so a billing failure is recognisable without matching a string.

Status	Code	Description
400	`MALFORMED_REQUEST`	The request could not be parsed.
401	`KEY_UNKNOWN`	Unknown API key.
401	`SESSION_EXPIRED`	The session token is invalid or has expired.
401	`SESSION_REVOKED`	The session was ended because its API key or entitlements changed.
401	`TOKEN_INVALID`	Unknown or revoked API token.
401	`TOKEN_MISSING`	No API token. Send Authorization: Bearer <your token>.
402	`QUOTA_EXHAUSTED`	The included allowance for this capability is used up for the current period.
403	`CAPABILITY_NOT_ENABLED`	This capability is not enabled for your account. See :doc to enable it.
403	`CAPABILITY_NOT_GRANTED_TO_KEY`	Your account has this capability, but this API key was not granted it.
403	`ENGINE_NOT_ENABLED`	This routing engine is not enabled for your account. Omit `engine` or choose an engine that is.
403	`KEY_IP_NOT_ALLOWED`	This API key is not permitted from your IP address.
403	`KEY_REVOKED`	This API key has been revoked or has expired.
403	`NOT_AUTHORIZED`	This operation is not permitted for these credentials.
403	`OPEN_API_DISABLED`	Open Platform access is not enabled for this account.
404	`JOB_NOT_FOUND`	No such job, or it belongs to another account.
404	`OPEN_NOT_FOUND`	Not Found
404	`RESOURCE_NOT_FOUND`	The referenced resource does not exist.
409	`JOB_NOT_FINISHED`	The job has not finished yet. Poll the job, or wait for the callback.
409	`USE_STANDARD_PATH`	Send this call to the standard path: the same call to the Open Platform /v1/plan/* (see `reason`).
410	`JOB_RESULT_EXPIRED`	The result has expired and is no longer available. Submit the request again.
410	`RESOURCE_EXPIRED`	The referenced resource has expired. Upload it again.
413	`REQUEST_TOO_LARGE`	The request body is too large. Upload large payloads as a reusable resource instead.
422	`CALLBACK_NOT_VERIFIED`	Verify the callback endpoint first: POST /v1/webhooks/verify and echo the challenge back.
422	`CALLBACK_URL_UNSAFE`	The callback URL must be a public HTTPS endpoint.
422	`PLAN_REFINE_REFUSED`	The plan cannot be refined here (see `reason`). Refine it with routing.refine, with the stops to keep in `freeze`.
422	`SOLVE_INFEASIBLE`	No plan satisfies every constraint. Check time windows, capacities and skills.
422	`UNSUPPORTED_REGION`	That routing region is not available. Use NA, EU, AU or ASIA.
422	`VALIDATION_FAILED`	The request failed validation. See details.
424	`ENGINE_REJECTED`	The routing engine refused this problem. Its reason is included where available.
429	`CONCURRENCY_LIMIT`	Too many solves are already running for this account. Retry when one finishes.
429	`RATE_LIMITED`	Too many requests. Please retry after the indicated delay.
429	`SNAPSHOT_LIMIT_REACHED`	A distance snapshot cannot be opened: a limit is reached (see `limit`). Close a snapshot no longer in use, or call without `matrix`.
500	`INTERNAL_ERROR`	An unexpected error occurred. Quote the request_id when contacting support.
502	`ENGINE_UNAVAILABLE`	The routing engine is temporarily unreachable. Please retry.
503	`OPEN_PLATFORM_DISABLED`	The open platform is temporarily unavailable.
503	`OPEN_UNAVAILABLE`	The open platform is temporarily unable to verify your credentials. Please retry.
504	`SOLVE_TIMEOUT`	The solve exceeded the synchronous budget. Send the same request with "mode":"async" and collect the result from the job.