Errors & Rate Limits

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

---

Error response shape

Errors return a JSON body with a detail field (FastAPI convention):

{ "detail": "Access denied to this task" }

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

{
  "detail": [
    {
      "loc": ["body", "messages"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

Status codes

Status	Meaning	Common causes
200	OK	Successful synchronous response.
202	Accepted	Background run dispatched — see Async & Background Runs.
400	Bad Request	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.
404	Not Found	Unknown task/run/agent, or a run the caller isn’t allowed to see (existence is hidden as 404, not 403).
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 enforced per org + user (or, for widget requests, per API key). Verified default limits (configurable per environment):

Endpoint class	Default limit
POST /api/run	30 requests / min
List/get/manage tasks (/api/tasks*)	100 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.

---

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.

See Authentication for the full token flow.