Error codes

Every error response — whatever the HTTP status — shares the same envelope, EnvelopedErrors, wrapping one or more Error objects:

{
  "errors": [
    {
      "code": "INVALID_VALUE",
      "message": "The field value is not valid."
    }
  ]
}

Field	Type	Description
`code`	string	Stable identifier for the error type. Branch your error handling on this field, not on the HTTP status alone or on the response’s description in the OpenAPI spec (see the section below on this) — several `code` values can share the same status.
`message`	string	Default, human-readable message. Useful for logs; not meant to be parsed.
`properties`	object	Optional extra context for the error, when the API provides any. Not documented per `code` yet — see the warning further down this page.

errors is an array: a single response — typically a 400 on plan/resource creation — can report several invalid fields at once.

Reference table

The API currently defines 11 business error codes:

`code`	HTTP status	Default message	Returned when
`INVALID_INPUT`	400	The payload cannot be parsed.	The request body isn’t valid JSON, or doesn’t match the expected schema (wrong type, missing required field).
`ID_NOT_UNIQUE`	400	The payload contains a collection with an id repeated multiple times.	A collection in the payload (e.g. `resources`, `orders`) has the same `id` on more than one item.
`KEYS_NOT_UNIQUE`	400	The payload contains a collection with the keys repeated multiple times.	A collection has a repeated business key other than `id` (e.g. a tag or reference field expected to be unique).
`INVALID_ID_REFERENCE`	400	The id reference contains an id that does not exist.	A field references an `id` that doesn’t match anything else in the payload or system (e.g. a `resourceId` that doesn’t exist).
`INVALID_VALUE`	400	The field value is not valid.	A field’s value fails a validation rule — format, range, or allowed values.
`PRECONDITION_FAILED`	400	A precondition failed.	The action requires the target resource to be in a particular state, and it isn’t (e.g. acting on an already-deleted or already-archived object).
`NOT_IMPLEMENTED`	400	Not yet implemented.	The requested behavior is recognized but not available yet. Despite the name, this returns 400, not 501 — treat it as a client-facing “not supported” rather than a server capability gap.
`NOT_AUTHENTICATED`	401	The caller is not authenticated.	No access token was sent, or it’s missing, malformed, or expired. See Authentication and API keys.
`NOT_ALLOWED`	403	The requested action is not allowed.	The caller is authenticated but doesn’t have permission for this specific action.
`NOT_FOUND`	404	The requested object could not be found.	The resource addressed by the URL doesn’t exist, or isn’t visible to the caller (the API doesn’t distinguish the two, to avoid leaking existence of resources you can’t access).
`INTERNAL_SERVER_ERROR`	500	The server encountered an unexpected condition that prevented it from fulfilling the request.	Unexpected server-side failure, unrelated to the request’s content. If this persists, contact support with the request’s timestamp.

This list is not yet exposed as a formal enum on the Error.code field in the API reference schema — it’s compiled from the current server implementation. If you’re generating a client from openapi.yaml, don’t assume this table is exhaustive for future versions; check the changelog when upgrading.

Same HTTP status, different `code`

The HTTP status alone doesn’t tell you which business error occurred — most statuses map to several codes (all of INVALID_INPUT, ID_NOT_UNIQUE, KEYS_NOT_UNIQUE, INVALID_ID_REFERENCE, INVALID_VALUE, PRECONDITION_FAILED, and NOT_IMPLEMENTED return 400). Always read code, not just the status. Conversely, you may see a 403 documented under either “Forbidden” or “Unauthorized” depending on the endpoint in the API reference — this naming isn’t consistent across the spec, but both cases behave identically: HTTP 403 with code: "NOT_ALLOWED". Match on code, not on the response name shown in the reference.

`properties`

The exact keys returned in properties for each code (for example, which field name or invalid value is included in an INVALID_VALUE or INVALID_ID_REFERENCE error) are not documented in the current API reference and need confirmation from the backend team before being published here. Treat any properties content as informational and not stable until this section is updated.

What this page doesn’t cover

Infeasible plans are not an error. Submitting a plan the engine can’t fully satisfy still returns a normal 200/201 — the plan is accepted, and unplanned stops or constraint violations show up in the solution (unaffectedStopIds, violations) rather than as an Error. See Handling infeasibility.
Rate limiting. The OTP-related endpoints (/auth/mfa/resendOTP, /login/resendOTP) return a 429 when called too often, but currently without a structured JSON body — it doesn’t follow the EnvelopedErrors format described above.

API

Data model

Changes

Reference table

Same HTTP status, different `code`

`properties`

What this page doesn’t cover

See also

​Reference table

​Same HTTP status, different code

​properties

​What this page doesn’t cover

​See also

Reference table

Same HTTP status, different `code`

`properties`

What this page doesn’t cover

See also