Errors & Rate Limits

Base URL: https://agent-api.auteryn.ai

---

Error response shape

Errors return a JSON body with a detail field:

{ "detail": "Access denied to this task", "request_id": "3f9c2a…" }

detail is usually a human-readable string. For request-validation failures (422) it is an array describing each invalid field:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "messages"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

When the request has an ID, the body includes it as request_id and the response as the X-Request-ID header. Quote it when you contact support. A few errors also carry a machine-readable code and a details object.

---

Status codes

Status	Meaning	Common causes
200	OK	Successful synchronous response.
202	Accepted	Background run dispatched — see Async & Background Runs.
400	Bad Request	Missing X-Agent-Id header, empty messages, last message not from the user, no user query, or a messaging source pointed at a non-customer-facing agent.
401	Unauthorized	Missing / invalid / expired JWT or API key.
402	Payment Required	Out of credits (pre-flight credit check failed).
403	Forbidden	Token valid but no access to this agent/task; guest using a disallowed endpoint; a member answering a sensitive approval; an agent token calling an endpoint outside its seven or sending another agent’s X-Agent-Id.
404	Not Found	Unknown task/run/agent, or a run the caller isn’t allowed to see (existence is hidden as 404, not 403).
409	Conflict	A run_id already in use; a task_id that another organization already holds (That task_id is unavailable.); a resume with no stopped run; an answer to an input request that has closed; a comment to a run that isn’t running.
422	Unprocessable Entity	Request body failed schema validation.
429	Too Many Requests	Rate limit exceeded — see below.
5xx	Server Error	Unexpected failure. Retry with backoff; if persistent, contact support.

---

Rate limits

Rate limits are counted per organization and user, over a one-minute window:

Endpoint	Limit
POST /api/run	30 requests / min
GET /api/tasks	100 requests / min
GET /api/retrieve, GET /api/knowledge-bases/{kb_id}/retrieve	60 requests / min

429 response

When a limit is exceeded the response includes a Retry-After header (seconds) and a descriptive detail:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{ "detail": "Rate limit exceeded. 31/30 requests. Retry after 42s" }

Handling: back off for the number of seconds in Retry-After, then retry. Use exponential backoff with jitter for repeated failures. Responses have no X-RateLimit-* headers, so Retry-After is the signal to read.

---

Auth errors

Status	Fix
401	Re-run the JWT exchange — the token expires after 1 hour. Ensure Authorization: Bearer <jwt> is present.
403	Check the X-Agent-Id maps to an agent your org can access, and that the task belongs to you. An agent token also needs X-Agent-Id to be the agent it was exchanged for, and a task that token’s agent started.

See Authentication for the full token flow.