Error envelope
All public endpoints return a uniform envelope on failure:
json
{ "error": "human-readable message" }
Validation errors include the first failing field's message; the platform never echoes internal error details or stack traces.
Status codes
| Status | Meaning |
|---|---|
400 | Malformed JSON or missing path/query parameters. |
401 | Missing or invalid authentication. |
403 | Authenticated but not authorized — wrong agent, agent inactive, external triggers disabled, etc. |
404 | Resource not found, or hidden from the caller. |
409 | Conflict — typically a backward state transition on a run. |
422 | Payload failed schema validation. |
429 | Rate limit exceeded. |
5xx | Platform or upstream failure. Retry with backoff. |
Idempotency
The following endpoints are idempotent on a caller-supplied key:
| Endpoint | Idempotency key |
|---|---|
/api/agents/{id}/runs/register | (agentId, externalRunId) |
/api/agents/{id}/runs/ingest | (agentId, externalRunId) |
Re-issuing a call with the same key updates the existing run and returns the same runId.
Rate limits
Hot endpoints are rate-limited per agent. The default budget is approximately:
| Endpoint | Limit |
|---|---|
POST /api/agents/{id}/runs/trigger | 20 req / min |
POST /api/runs/{id}/callback | 20 req / min |
POST /api/agents/{id}/runs/ingest | 60 req / min |
Exceeding the budget returns 429. Back off and retry; the platform does not currently emit Retry-After.