Errors and pagination

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
}

REST list endpoints keep their legacy resource-key shape by default. Main list endpoints also support ?shape=envelope (alias: ?response_shape=cli) for the same agent-friendly envelope used by CLI JSON list output:

{
  "resource": "issues",
  "items": [],
  "total": 0,
  "limit": 25,
  "offset": 0,
  "nextOffset": null,
  "truncated": false,
  "hint": null
}

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",
  "code": "optional_machine_code"
}

Missing authentication on a shared guarded route returns:

{ "error": "Unauthorized", "code": "unauthorized" }

Unknown /api/* paths return:

{ "error": "Not found", "code": "not_found" }

OAuth profile selection uses stable machine-readable error values:

Error	Meaning
`no_profiles_authorized`	The connection is valid but has no currently usable grants
`profile_required`	More than one profile is usable; the response includes safe `profiles` summaries
`invalid_profile`	The selector is unknown, cross-connection, revoked, or unavailable
`profile_selector_not_supported`	An API-key request tried to switch actor identity

These errors occur before the requested business handler reads or changes its resource. invalid_profile deliberately does not reveal whether the rejected reference exists under another connection.

Initiative link resolution errors

The POST initiative issue, initiative milestone, and initiative-target issue link routes normalize accepted identifiers before writing the relationship. They return these stable messages when resolution fails:

Status	`error`	Meaning
`400`	`Invalid resource identifier`	The issue or milestone reference has an unsupported format.
`404`	`Not found`	The resource is missing, inaccessible, in another organization, outside the initiative’s project scope, or an unsupported projectless milestone.
`409`	`Resource identifier is ambiguous`	The reference matches more than one accessible resource in scope.
`500`	`Failed to resolve resource access`	Atoll could not complete resource resolution.

Missing request fields use the route-specific issue_id is required or milestone_id is required message. Successful writes store the canonical UUID, even when the request used a number, prefix, or milestone name.

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

Directly requested project-bound resources, including issues and their child resources, milestones, board columns, status updates, PR links, and issue activity, use 404 to conceal a missing, wrong-organization, wrong-parent, or unreadable resource. A readable project or resource with insufficient write access returns 403; collection reads can omit unreadable linked resources. Organization-level role failures may also return 403.

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

Start here

User guide

Agent guide

CLI

API reference

Integrations

Admin

Changelog

Troubleshooting

Errors and pagination

Success responses

Error format

Initiative link resolution errors

Common status codes

Plan limit errors

Deletion permissions

​Success responses

​Pagination

​Error format

​Initiative link resolution errors

​Common status codes

​Plan limit errors

​Deletion permissions

Success responses

Pagination

Error format

Initiative link resolution errors

Common status codes

Plan limit errors

Deletion permissions