Errors, retries, and warnings

​

Error families

from kardinal import KardinalLimitError, KardinalValidationError

try:
    plan = k.routing.plans.submit(plan_input)
except KardinalValidationError as e:
    print(e.code)    # INVALID_VALUE, ID_NOT_UNIQUE, ...
    print(e.errors)  # every error of the response, not only the first
    raise
except KardinalLimitError as e:
    print(e.details)  # which limit was hit
    raise

import { KardinalLimitError, KardinalValidationError } from "@kardinal-ai/sdk";

try {
  plan = await k.routing.plans.submit(planInput);
} catch (e) {
  if (e instanceof KardinalValidationError) {
    console.log(e.code); // INVALID_VALUE, ID_NOT_UNIQUE, ...
    console.log(e.errors); // every error of the response, not only the first
  } else if (e instanceof KardinalLimitError) {
    console.log(e.details); // which limit was hit
  }
  throw e;
}

​

Common error attributes

​

Validation errors

​

Quotas and rate limits

• Plan-size limit (too many resources, orders, or stops, or more than 4 stops in an order without successiveStops): errors also holds one INVALID_VALUE entry 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.
• Insufficient credits: top up your credits in the Console.

​

What the SDKs retry

​

Client-side errors

• UnknownFieldError — submit refuses 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 misspelled operationDurationn would leave the stop with no service time, and the plan would still look valid.
  Unknown field(s) in the plan:
    plan.resources[0].maxWorkingDurationn       (did you mean maxWorkingDuration?)
    plan.orders[0].stops[0].operationDurationn  (did you mean operationDuration?)
  
  update sorts 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.ValidationError in Python, ZodError in TypeScript.
• Missing key — MissingApiKeyError and EmptyApiKeyError, raised when creating the client — see API key resolution.

​

Warnings on successful calls

plan = k.routing.plans.submit(plan_input)
for warning in plan.warnings:
    print(warning.code, warning.properties)  # for example, maxOptimizationDuration clamped

plan = await k.routing.plans.submit(planInput);
for (const warning of plan.warnings) {
  console.log(warning.code, warning.properties); // for example, maxOptimizationDuration clamped
}