Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Error response shape, every status code the API returns and what to do about each, including the scheduled-agent 502 and 503 cases, plus rate-limit headers. Read when a call fails.
detail field:
{
"detail": "Session not found"
}
{
"detail": {
"error": "validation_error",
"message": "Field 'agent' is required",
"field": "agent"
}
}
| Code | Meaning | When you will see it |
|---|---|---|
400 | Bad Request | Validation failed - missing or invalid fields, malformed JSON. |
401 | Unauthorized | API key is missing, invalid, or expired. |
403 | Forbidden | Key is valid but lacks the required scope, or the user is not a member of the target organization. |
404 | Not Found | The requested resource does not exist, or is not visible to the key’s scope. |
409 | Conflict | The resource is in an invalid state for the requested operation (e.g. pausing an already-paused session). |
413 | Payload Too Large | The request body exceeds the maximum allowed size. |
422 | Unprocessable Entity | The body parsed but failed schema validation, for example a wrong field type or an unknown enum value. Check the endpoint’s parameters. |
429 | Too Many Requests | Rate limit exceeded. See Rate Limits. |
500 | Internal Server Error | An unexpected error occurred. If persistent, contact support. |
502 | Bad Gateway | On POST /scheduled-agents/{id}:run, the launch itself failed (unknown template, deleted Slack integration). detail carries the reason; this is the on-demand run surfacing what a cron tick would fail on silently. |
503 | Service Unavailable | On scheduled-agent create or update, the scheduler is not configured in this environment. Create the agent disabled and drive it with :run. Elsewhere, an upstream dependency is down; retry once. |
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets. |
429 response, the Retry-After header tells you how many seconds to wait:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1748052600
{
"detail": "Rate limit exceeded. Retry after 30 seconds."
}
detail field for a human-readable message.response = requests.get(url, headers=headers)
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 30))
time.sleep(retry_after)
response = requests.get(url, headers=headers)
elif response.status_code >= 400:
error = response.json()
raise Exception(f"API error {response.status_code}: {error['detail']}")