KardinalError and can be imported from the package root.
Error families
A code the SDK doesn’t know yet falls back to the family matching its HTTP status, so a new code added by the API doesn’t go unnoticed. For the meaning of each code, see the
Error schema in the API Reference.
Common error attributes
Every exception carries the same attributes, named in each language’s case:retryable is true for a 429, and for a 5xx or a connection error — except when a submit may have reached the server, since the plan may then already exist.
Validation errors
A400 means the API refused the plan as sent. errors holds every problem found, each with its code and, in properties.path, the field concerned: fix them all before submitting again rather than one per attempt. Most structural mistakes never reach the API: the SDKs catch them locally first (see Validating locally before you spend credits).
Quotas and rate limits
403: usually a limit. A 403 NOT_ALLOWED usually means a limit was hit. From 1.1.0, the SDKs sort a 403 by what its response carries, and details still tells the cases apart. Three cases are limits, and each raises KardinalLimitError:
- Plan-size limit (too many resources, orders, or stops, or more than 4 stops in an order without
successiveStops):errorsalso holds oneINVALID_VALUEentry per exceeded limit, naming the field and the allowed value. Shrink the plan. - Daily or monthly optimization quota: wait, or ask for a higher quota. A restart with
plans.startcounts as one optimization against this quota. - Insufficient credits: top up your credits in the Console.
403 that isn’t a limit, and each raises another class from 1.1.0:
- A revoked or regenerated key raises
KardinalAuthError, with.statusset to403.detailsisthe token is invalid, on every call, reads and deletes included. It isn’t a401: only a missing, malformed, or expired key gets a401. Code that testsstatus == 401to detect a key problem therefore misses a revoked key. CatchKardinalAuthErrorfrom 1.1.0, or comparedetailswiththe token is invalidin any version. Use the current key from the Console. - An archived plan, updated, stopped, or restarted without
forceraisesKardinalValidationError, anderrorshas no field path.detailsisCannot update an archived plan, except with the 'force' query param. Passforceto unarchive the plan, knowing that a forced update or restart bills every stop again (see Re-optimizing withupdate).
403 raises KardinalForbiddenError. Read its details and errors to find the cause.
In 1.0.x, every 403 raises KardinalLimitError, and details is the only way to tell the cases apart.
See Reaching a limit (403) and Pricing and credits for the values.
429: a temporary overload, not a quota. It comes with an empty body. The SDKs retry it on their own, honouring a Retry-After header if the API sends one, and backing off otherwise. See Temporary overload (429).
What the SDKs retry
The number of retries is set by
max_retries / maxRetries (3 by default), with a growing, randomized delay between attempts. submit is never retried because the API has no idempotency key: a retried submit could create the plan twice. After a failed submit, check with plans.list whether the plan exists before submitting again.
Client-side errors
Some errors are raised before any request is sent:-
UnknownFieldError—submitrefuses a plan containing a key no model declares, and lists each one with its path and the closest real field name. The API would drop such a key without an error: a misspelledoperationDurationnwould leave the stop with no service time, and the plan would still look valid.updatesorts unknown keys by origin: a key the server sent, from a field added after your SDK version, is sent back untouched; a key you added is refused as a typo. To send a field the API supports but your SDK version doesn’t know yet, name it explicitly:allow_unknown=["aNewField"](Python) or{ allowUnknown: ["aNewField"] }(TypeScript). A name listed there is allowed anywhere in the plan, so prefer distinctive names. -
Model validation — a missing required field or a wrong type fails when the plan is built or parsed:
pydantic.ValidationErrorin Python,ZodErrorin TypeScript. -
Missing key —
MissingApiKeyErrorandEmptyApiKeyError, raised when creating the client — see API key resolution.
- Python
- TypeScript
On a plan this SDK didn’t read from the API (built by hand, or loaded from a file),
update can’t tell where an unknown key came from: it raises an UnknownFieldWarning through Python’s warnings module, only for a key within two edits of a real field, and sends the plan.Warnings on successful calls
When the API accepts a plan but amends part of it — amaxOptimizationDuration clamped to your agency’s cap, crow-fly distances forced in the sandbox, predictive traffic turned off — submit, update, and replace return the amendments in warnings:
get never returns them, only the amended values. Solutions, objective lists, and the references returned by start and stop carry a warnings field too. The Warning schema in the API Reference lists what each one means.
Every replacement currently has the code INVALID_VALUE and the message The field value is not valid., the same as a validation error. Other warnings can use INVALID_VALUE too, or ID_NOT_UNIQUE and KEYS_NOT_UNIQUE for duplicates. The code and the message don’t tell you what happened. Only properties.path does, and it is stable. In Python, read it with (warning.properties or {}).get("path"). properties is a dict and can be None, so warning.properties.path raises an AttributeError. In TypeScript, read it with warning.properties?.path.
Currently, the API replaces a value in three cases. It lowers maxOptimizationDuration to your agency’s cap. In the sandbox, it turns predictive traffic off and forces crow-fly distances. The first case has the path maxOptimizationDuration. The other two share the path resources.N.vehicleProfile. N is the position of the resource in the plan the API returns, and that position follows the order of the plan you sent. A warning on any other path means the API accepted a value that is probably a mistake. It replaced nothing, so check that value.
The text in properties.details is not stable. It is English text written by the API. It contains the internal agency id. It writes durations in an internal format such as 6h0m0s. Don’t show details or message to the planner. Build your own message from the path and from the value stored at that path in the plan the API returned. For example:
- The path is
resources.1.vehicleProfile, and the stored value there is{"type": "fly", "kmph": 45}. Take theidof that resource,truck-2, and showtruck-2: straight-line distances at 45 km/h. - The path is
maxOptimizationDuration, and the stored value isPT6H. ShowOptimization time reduced to 6 hours.
fly vehicle included, and you get one line for all of them. A vehicle sent with withTraffic: true gets a second warning on the same path, because the sandbox also turns its traffic off.
- Python
- TypeScript
submit, update, and replace log one line per kind of warning on the kardinal logger, at the WARNING level. Python prints it on stderr, with no logging setup. To silence the lines, raise the level of the logger:logging.config.dictConfig after the first warning, set disable_existing_loggers to False in that configuration. Otherwise, dictConfig disables the kardinal logger.warnings of the returned plan instead. When the API rejects a plan, its warnings come with the error, and the SDKs don’t report them.
