Errors are returned as { "code": "…", "message": "…" }. The most useful signal on the start path is the HTTP status, which tells you whether to retry.
| HTTP | Meaning | Retry? |
|---|
| 202 | Accepted but queued — no agent was free; the drain loop will dispatch it | — |
| 503 | No agent is currently free (Retry-After: 5) | Yes, after the delay |
| 429 | The overflow queue is at maxdepth (Retry-After: 10) | Yes, after the delay |
| 400 | No agent matches the requested selectors, or the definition/tenant is invalid | No — fix the selector or definition |
| HTTP | Meaning |
|---|
| 400 | invalid tenant — the CPET headers match no configured tenant; or the signal name doesn’t match a declared Wait event; or a required signal field is missing |
| 400 | The engine does not support signalling (a v2 engine is required) |
| 403 | The route requires a superadmin token (e.g. applying a migration plan, cross-tenant admin) |
| 404 | Unknown instance or queue item |
| HTTP | Meaning |
|---|
| 403 | DELETE /workflow/queue/:id for an item that belongs to another tenant |
| 404 | Unknown queue item id |
See also Operations → Failure modes.
