Agents API errors

The Agents endpoints return errors using a flat envelope: a short error label plus a message field with the specific cause. This differs from the OpenAI-compatible nested envelope used by /v1/responses and /v1/conversations/*.

Envelope

{
  "error": "Not found",
  "message": "Agent 18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d not found."
}

Status reference

Status	error	Cause
400	Bad Request	Malformed request body — e.g. missing agentId on POST /v1/agents/runs, or a body that fails Zod schema validation.
401	Unauthorized	Missing, malformed, or revoked API key. Emitted by the auth middleware; the body is {"error": "Unauthorized", "message": "..."}.
404	Not found	agentId does not exist or is not visible to the caller; runId does not exist or the caller cannot read the underlying conversation. Per-agent permission denials also collapse to 404 — Kindo does not distinguish “missing” from “forbidden” on this surface.
422	Unprocessable Entity	Body parsed, but the request cannot be executed — required inputs[].name entries declared by the agent are missing from the request.
429	Too Many Requests	Org or user rate limit. Honors Retry-After when present.
500	Internal Server Error	Unexpected Kindo-side failure.

Unknown inputs[].name entries on POST /v1/agents/runs are silently dropped rather than rejected — only the missing-required case produces a 422. Re-fetch GET /v1/agents/{agentId} to confirm the canonical label list if a run isn’t picking up the values you expected.

Common causes by endpoint

POST /v1/agents/runs

A 422 Unprocessable Entity here means the request omitted a required inputs[].name declared on the agent. The labels are case-sensitive and must match exactly. Fetch GET /v1/agents/{agentId} to confirm the canonical list before retrying. (Triggers do not block this endpoint — an agent with hasTriggers: true can still be run directly.)

A 404 Not found here means the agentId is unknown to the caller — either it does not exist, or the user group does not grant access. Permission failures intentionally collapse to 404 and are not distinguished from “missing” in the response.

GET /v1/runs/{runId}

A 404 Not found here means either the runId is bogus, the caller cannot read the underlying conversation, or the run has been pruned by retention. The three cases are not distinguished in the response envelope.

A run that finished with status: "failure" is not an HTTP error — it returns 200 with a status payload. Inspect the status field, not the HTTP code, to detect agent-level failures.

POST /v1/runs/{runId}/restart

A 404 Not found means the run does not exist or the caller lacks access — the same collapse-to-404 behavior as GET /v1/runs/{runId}. The two cases are intentionally indistinguishable.

A 400 Bad Request indicates a malformed runId (not a valid UUID).

GET /v1/runs/{runId}/evals

Error behavior mirrors GET /v1/runs/{runId} — a 404 Not found means the run does not exist or the caller lacks access. The two cases are intentionally indistinguishable.

A 400 Bad Request indicates a malformed runId (not a valid UUID).

See also

• Authentication — 401 causes.
• Quickstart — input-label discovery flow that prevents 422 errors.