Skip to content
Kindo Kindo Docs

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

StatuserrorCause
400Bad RequestMalformed request body — e.g. missing agentId on POST /v1/agents/runs, or a body that fails Zod schema validation.
401UnauthorizedMissing, malformed, or revoked API key. Emitted by the auth middleware; the body is {"error": "Unauthorized", "message": "..."}.
404Not foundagentId 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.
422Unprocessable EntityBody parsed, but the request cannot be executed — e.g. required inputs[].name entries are missing, or the agent has triggers configured (hasTriggers: true) and cannot be run via this endpoint.
429Too Many RequestsOrg or user rate limit. Honors Retry-After when present.
500Internal Server ErrorUnexpected 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 either:

  • 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.
  • The agent has hasTriggers: true — agents with triggers are run by the trigger pipeline, not by this endpoint.

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.

See also