Error Codes
Errors are returned as { "code": "…", "message": "…" }.
Flow service
Section titled “Flow service”| Code | HTTP | Meaning |
|---|---|---|
ai-flow-json-request-parse-failed | 400 | Malformed request body |
ai-flow-request-required-field-not-found | 400 | A required field was missing |
ai-flow-query-parsing-failed | 400 | A query filter could not be parsed |
ai-flow-ctx-tenant-not-found | 400 | The CPET headers didn’t resolve to a tenant |
ai-flow-global-config-is-nil | 500 | The service booted without required global config |
A request to a tenant whose engine isn’t built returns 400 (dag execution engine for tenant … not found); an unknown conversation returns 400.
Starting a flow
Section titled “Starting a flow”The /workflow/start path shares the Workflows engine, so the same status semantics apply:
| HTTP | Meaning | Retry? |
|---|---|---|
| 202 | Queued — no agent free | — |
| 503 | No agent free (Retry-After: 5) | Yes |
| 429 | Queue full (Retry-After: 10) | Yes |
| 400 | No agent matches the selectors, or the flow/tenant is invalid | No |
At execution time a task fails if the endpoint it targets — a model, a gateway route, a vector store, or an embedder — is unreachable; the failure surfaces on the node and follows the task’s error: route.