Response envelopes
OpenAPI description says successful responses are { "data": <payload> } and errors are { "error": "<message>" }. That is true for configs, schemas, pipelines, and custom transformers.
Unwrapped bodies
These resources return the schema as specified, without a data wrapper:
| Resource | Success shape |
|---|---|
GET /api/health | { "status": "ok" } |
| Executions create/list/get/cancel | ExecutionRecord, { executions: [...] }, or { status: "cancel requested" } |
| Worker register/claim/running/heartbeat/finish/stats | Protocol objects (jobs, WorkerStats, …) |
Errors
Named in the spec: 400, 401, 404, 429, 500. Also used at runtime:
| Status | When |
|---|---|
| 409 | Cancel of missing/terminal execution; lost worker claim; custom-transformer unique name |
| 429 | Queue full; custom-transformer test concurrency cap |
| 503 | Scheduler/worker handlers not configured (not in OpenAPI) |
CRUD wrappers usually return a stable client string and log the real error. Scheduler/worker 500s often include err.Error(). Binding failures use { "error": "..." } (not oapi-codegen’s { "msg": "..." }).
Create execution: 202 Accepted. List executions is capped at 50.