> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```http theme={null}
DELETE /api/orgs/{orgId}/issues/{issueId}
```

For most workflows, use archive instead:

```http theme={null}
POST /api/orgs/{orgId}/issues/{issueId}/archive
```

Reverse it with:

```http theme={null}
DELETE /api/orgs/{orgId}/issues/{issueId}/archive
```