Errors and pagination

Understand Atoll response formats, pagination, plan limit errors, authorization errors, and common status codes.

Atoll returns JSON for API responses.

Success responses

Successful create requests usually return 201. Reads and updates usually return 200.

List responses include pagination fields:

{
  "items": [],
  "total": 0,
  "limit": 25,
  "offset": 0
}

Some CLI JSON output wraps list responses with additional metadata such as resource, nextOffset, truncated, and hint.

Pagination

List endpoints support:

Query param	Meaning
limit	Number of results, default 25, max 100
offset	Offset into the result set

Example:

curl -H "Authorization: Bearer $ATOLL_API_KEY" \
  "https://atollhq.com/api/orgs/$ATOLL_ORG_ID/issues?limit=100&offset=100"

Error format

Most errors return:

{
  "error": "message"
}

Common status codes

Status	Meaning
400	Invalid request or validation error
401	Missing or invalid authentication
402	Billing plan limit reached
403	Authenticated but not allowed
404	Resource not found or not visible
409	Conflict, such as duplicate dependency
429	Rate limited
500	Unexpected server error

Plan limit errors

Creation endpoints can return 402:

{
  "error": "Plan limit reached",
  "code": "PLAN_LIMIT_REACHED",
  "resource": "activeProjects",
  "plan": "free",
  "limit": 2,
  "usage": 2
}

resource can be:

• humans
• agents
• activeProjects
• activeIssues

Deletion permissions

Permanent task delete requires owner/admin access:

DELETE /api/orgs/{orgId}/issues/{issueId}

For most workflows, use archive instead:

POST /api/orgs/{orgId}/issues/{issueId}/archive

Reverse it with:

DELETE /api/orgs/{orgId}/issues/{issueId}/archive