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

# Errors, limits and pagination

> Handle Redbark Advisor API errors, rate limits and paginated lists.

## Error envelope

Every error has the same shape:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "client_archived",
    "message": "This client is archived.",
    "param": null,
    "request_id": "req_4f9c2a1b7d3e8f60"
  }
}
```

* `type` is the broad kind of error. See the table below.
* `code` is stable. Branch on it.
* `message` is for people. It can change, so do not parse it.
* `param` names the field at fault, or is `null`.
* `request_id` matches the `X-Request-Id` header. Quote it if you contact us.

| `type` | Status | Meaning |
| - | - | - |
| `invalid_request_error` | 400, 402, 404, 405, 409, 413, 415, 422 | The request is not valid, or the resource is in a state that does not allow it |
| `authentication_error` | 401 | The token is missing, wrong, expired or revoked |
| `permission_error` | 403 | The token lacks a scope, the call is admin only, or the member it acts as has left |
| `rate_limit_error` | 429 | Too many requests |
| `api_error` | 500, 502, 503 | Something went wrong on our side |

## Status codes

| Status | When |
| - | - |
| 200 | Success |
| 201 | Something was created |
| 400 | A field or the body is not valid |
| 401 | Authentication failed. See [Authentication](https://redbark.com/docs/advisor/api-reference/authentication.md#failed-authentication) |
| 402 | The firm has no active subscription |
| 403 | The call is not allowed for this token |
| 404 | No such resource in this firm, or no such route |
| 405 | The method is not allowed on this path. The `Allow` header lists the ones that are |
| 409 | The resource is in a state that does not allow this, or a limit is reached |
| 413 | The body is over 256 KiB |
| 415 | The body is not JSON |
| 422 | The field asks for something Advisor never keeps, such as a tax file number |
| 429 | Rate limited |
| 500 | Something went wrong. Try again |
| 502, 503 | A service we rely on did not answer. Try again in a moment |

## Common codes

### Request

| Code | Status | Meaning |
| - | - | - |
| `invalid_parameter` | 400 | A field does not match its schema. `param` names it |
| `invalid_json` | 400 | The body is not valid JSON, or not a JSON object |
| `invalid_cursor` | 400 | `cursor` is not one we issued |
| `invalid_client`, `invalid_checklist`, `invalid_message`, `invalid_report`, `invalid_value`, `invalid_webhook_endpoint` | 400 | The input was refused. `message` says why and `param` names the field |
| `route_missing` | 404 | No route matches the path |
| `method_not_allowed` | 405 | The path exists but not for this method |
| `payload_too_large` | 413 | The body is over 256 KiB |
| `unsupported_media_type` | 415 | Send the body with `Content-Type: application/json` |

### Billing and plan

| Code | Status | Meaning |
| - | - | - |
| `subscription_required` | 402 | The firm has no active subscription. It cannot add or invite clients or send checklists. An admin can subscribe in Settings, Billing |
| `client_limit_reached` | 409 | The plan's 20 active clients are in use. Archive a client to add another |

### Permission

| Code | Status | Meaning |
| - | - | - |
| `insufficient_scope` | 403 | The token lacks the scope this call needs. The message names it |
| `admin_required` | 403 | Only an admin can do this. A connected app acting as a non-admin member gets this |
| `member_removed` | 403 | The member the call acts as is no longer in the firm. For a key, that is the admin who made it |
| `not_message_author` | 403 | Only the member who wrote a message can change it |

### Not found

Each area has its own code, such as `client_not_found`, `document_not_found`, `member_not_found`, `report_not_found` or `webhook_endpoint_not_found`. All are 404. An id from another firm is treated as not found.

### Conflicts

| Code | Status | Meaning |
| - | - | - |
| `client_archived` | 409 | The client is archived, so this change is not allowed |
| `checklist_item_state` | 409 | The checklist item is not in a state that allows this, such as approving an item that was not submitted |
| `wrong_state` | 409 | The document is not in a state that allows this review step |
| `nothing_to_invite` | 409 | Everyone on the client with an email address has already joined |
| `last_admin` | 409 | The firm must keep at least one admin |
| `edit_window_closed` | 409 | A message can be edited for five minutes after it is posted |
| `connection_ended` | 409 | The bank connection has already ended |
| `value_never_kept` | 422 | A document type field asks for something Advisor never keeps, such as a tax file number. `param` names the field |
| `builtin_locked` | 409 | Redbark's built-in document types, fields and facts cannot be changed. Add your own instead |
| `webhook_endpoint_limit` | 409 | The firm already has 16 webhook endpoints |

## Rate limits

Each API key, and each connected app, may make 120 requests a minute. The window is a fixed minute.

Every successful response carries these headers:

| Header | Value |
| - | - |
| `RateLimit-Limit` | The limit, 120 |
| `RateLimit-Remaining` | Requests left in this window |
| `RateLimit-Reset` | Seconds until the window resets |

Over the limit, the API answers `429` with code `rate_limited` and a `Retry-After` header in seconds. Wait that long, then try again.

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. The limit is 120 a minute.",
    "param": null,
    "request_id": "req_9a0b1c2d3e4f5a6b"
  }
}
```

## Retrying

* Retry `429` after `Retry-After`.
* Retry `500`, `502` and `503` with a backoff.
* Do not retry `400`, `401`, `402`, `403`, `404` or `409` without changing something first.
* Not every write is safe to repeat. A `POST` that creates something can create it twice. Read before you retry a create.

## Pagination

Lists return one page at a time:

```json theme={null}
{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "eyJ...",
  "next_page_url": "https://advisor.redbark.com/api/v1/clients?limit=25&cursor=eyJ..."
}
```

* `limit` sets the page size, from 1 to 100. The default is 25.
* When `has_more` is `true`, pass `next_cursor` as `cursor` to get the next page, or call `next_page_url`.
* Keep the other query parameters the same while you page.
* When `has_more` is `false`, `next_cursor` and `next_page_url` are `null`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.