Errors

Non-2xx responses follow this shape:

{
  "error": {
    "code": "<stable_code>",
    "message": "<human description>"
  }
}

Use code for routing logic; show message (or your translation of the code) to your users.

HTTP status taxonomy

Status	Meaning
`400`	Bad request — malformed JSON, missing field, invalid value.
`401`	Unauthenticated — `X-Platform-Key` or `X-Admin-Key` missing or invalid.
`403`	Authenticated but the action is denied (policy, missing scope).
`404`	Resource doesn’t exist.
`409`	Conflict — resource is in a state that prevents the action.
`429`	Quota exceeded or rate-limited. Retry after some time.
`500`	Internal server error. Report it.
`502`	Backend (Docker, engine) returned an unrecoverable error.
`503`	Orchestrator starting up or out of capacity.
`504`	Backend (engine boot, health probe) timed out.

Error codes

Auth

Code	Status	Cause	Action
`INVALID_PLATFORM_KEY`	401	Header missing or unknown.	Fix the key.
`INVALID_ADMIN_KEY`	401	Admin call without (or wrong) `X-Admin-Key`.	Fix the key.

Product / engine state

Code	Status	Cause	Action
`PRODUCT_NOT_FOUND`	404	Product slug or ID doesn’t exist.	Re-register the product.
`ENGINE_NOT_FOUND`	404	No engine for this `user_id`.	Provision one (or pass `auto_provision=true`).
`ENGINE_ALREADY_EXISTS`	409	`POST /engines/provision` against an existing engine.	Use `/admit` if you want idempotent behavior.
`ENGINE_NOT_RUNNING`	409	`POST /stop` or `/rotate-key` against an engine that isn’t running.	Start it first or skip.
`ENGINE_ALREADY_RUNNING`	409	`POST /start` against a running engine.	No-op; ignore.

Policy

Code	Status	Cause	Action
`QUOTA_EXCEEDED`	429	Product at `max_engines` limit.	Destroy unused engines or raise the policy limit.
`RATE_LIMITED`	429	Per-product RPM exceeded.	Back off; respect `Retry-After` if present.
`POLICY_DENIED`	403	Action not permitted by the product’s policy.	Check the policy; update if needed.

Resource exhaustion

Code	Status	Cause	Action
`PORT_EXHAUSTION`	503	No free port in `[ORCH_PORT_MIN, ORCH_PORT_MAX]`.	Widen the port range or destroy unused engines.

Backend

Code	Status	Cause	Action
`BACKEND_ERROR`	502	Docker / subprocess returned an error.	Check the orchestrator logs; usually transient.
`BOOT_TIMEOUT`	504	Engine didn’t reach `/health: ok` within `ORCH_BOOT_TIMEOUT_S`.	Check the engine’s logs. The engine’s startup is misbehaving.

Internal

Code	Status	Cause	Action
`INTERNAL_ERROR`	500	Unexpected server bug.	File an issue with the request and timestamp.

Retry guidance

Code	Retry?	How
`RATE_LIMITED`	Yes	Exponential backoff. Honor `Retry-After`.
`QUOTA_EXCEEDED`	No	Hard limit; fix the policy or destroy engines.
`BACKEND_ERROR`	Once	Could be a transient Docker hiccup. After one failed retry, surface to the user.
`BOOT_TIMEOUT`	No	The engine itself is broken. Investigate.
`503` (orchestrator starting)	Yes	Back off 1–5s.
`INVALID_PLATFORM_KEY`	No	Fix the key.
`ENGINE_NOT_FOUND`	No (in lookup)	Provision instead.

Error envelope examples

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Product 'demo' at max_engines limit (1000)."
  }
}

{
  "error": {
    "code": "BOOT_TIMEOUT",
    "message": "Engine 5c2f... did not become healthy within 60s."
  }
}

The error.message is for humans; don’t depend on its exact text.

Architecture

BAP Engine

Engineering

HTTP status taxonomy

Error codes

Auth

Product / engine state

Policy

Resource exhaustion

Backend

Internal

Retry guidance

Error envelope examples

See also

​HTTP status taxonomy

​Error codes

​Auth

​Product / engine state

​Policy

​Resource exhaustion

​Backend

​Internal

​Retry guidance

​Error envelope examples

​See also

HTTP status taxonomy

Error codes

Auth

Product / engine state

Policy

Resource exhaustion

Backend

Internal

Retry guidance

Error envelope examples

See also