> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/v-1/docs/api/errors-and-pagination/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Errors & pagination

> Rightbrain API error forms, HTTP status codes, cursor-based pagination, response headers, and idempotency on public webhook triggers.

This page covers shared error, pagination, response-header, and idempotency conventions. Endpoint-specific responses remain authoritative in the API reference.

## Errors

Rightbrain uses several error forms:

* Domain errors use `detail.reason`, `detail.message`, and sometimes an error-specific details field.
* Request validation usually returns a `detail` array. Items can use either `msg` or `message`.
* Some routes return a string `detail`.
* Authentication failures use a top-level `error` object.
* Gmail integration preconditions use `detail.code`.
* MCP OAuth startup failures can be returned through redirect query parameters.

The [Error reference](/docs/api/error-reference) documents these forms, common reason codes, run failures, and recovery guidance.

### Status codes

| Status | Meaning                                                                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Malformed request or a domain validation failure.                                                                                                                                                       |
| `401`  | Missing or invalid credentials.                                                                                                                                                                         |
| `402`  | Billing or credit state prevents execution. Resolve the account state before retrying.                                                                                                                  |
| `403`  | A permission check failed. The resource may also be hidden or unresolved by that check.                                                                                                                 |
| `404`  | A resource or route was not found. The response can be structured or a string `detail`.                                                                                                                 |
| `409`  | Conflict with the resource's current state — for example, running an agent with a `revision_id` that does not match the session's revision, or acting on an approval request that is no longer pending. |
| `422`  | Schema or application validation failed.                                                                                                                                                                |
| `500`  | Execution or internal failure. The body can be structured JSON, string JSON, or plain text.                                                                                                             |

## Pagination

Most list endpoints return a paginated envelope: a `pagination` object plus a `results` array.

**`Paginated response`**

```json title="Paginated response"
{
  "pagination": {
    "next_cursor": "0190a234-8dc6-6d08-aea9-928fcecad8f2",
    "has_next": true,
    "page_limit": 100
  },
  "results": [ ]
}
```

Page with two query parameters:

**`cursor`** `string`

Pass the previous response's `pagination.next_cursor` to fetch the next page. Omit it for the first page.

---

**`page_limit`** `integer`

The maximum number of items per page.

---

Stop when `has_next` is `false` (`next_cursor` will be `null`).

**`First page`**

```bash title="First page"
curl "https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run?page_limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**`Next page`**

```bash title="Next page"
curl "https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task/{task_id}/run?page_limit=100&cursor=0190a234-8dc6-6d08-aea9-928fcecad8f2" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Endpoints that return plain arrays

Some endpoints return a bare JSON array with no `pagination` envelope:

* `GET .../model`
* `GET .../input_processor`
* `GET .../task_forwarder_type`
* `GET .../guardrail`
* `GET .../api_key`
* `GET .../task/{id}/share`
* Skill source lists
* Skill revision lists
* Trigger-level event lists

## Response headers

Task runs return two headers you can use for correlation and debugging:

* `x-task-run-id` — the ID of the run just executed.
* `x-task-revision-id` — the revision that served it.

## Idempotency

Public webhook triggers accept an idempotency key so a retried delivery is not processed twice. Use it when the caller might resend the same event. See [Triggers & runs](/docs/concepts/triggers-and-runs) for configuring public webhook invocation.

#### [Run tasks via the API](/docs/api/run-tasks)

The run endpoint, its response, and its headers.

#### [Authentication](/docs/api/authentication)

Get past 401 and 403 with the right credential.

> Build reliable AI agents that run inside your existing tools and workflows. Rightbrain developer documentation.