> 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/error-reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Error reference

> Rightbrain API error response forms, authentication and permission failures, validation errors, integration preconditions, run failures, and retry guidance.

Rightbrain errors are not represented by one universal envelope. The forms below cover the shared contracts and high-impact exceptions. Check each endpoint's API reference for its documented statuses and endpoint-specific errors.

## Response forms

| Form                     | Where it appears                                                   | Fields to inspect                                                      |
| ------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| Domain error             | Application errors such as permission checks and missing resources | `detail.reason`, `detail.message`, and an error-specific details field |
| Request validation       | FastAPI and Rightbrain request validators                          | `detail[]`; each item has `type`, `loc`, and either `msg` or `message` |
| Service validation       | Some clone and dependency checks                                   | `detail.type: "validation_error"` and `detail.errors[]`                |
| Plain detail             | Route, file, session, and other endpoint-specific errors           | String `detail`                                                        |
| Authentication error     | Requests rejected before the application                           | Top-level `error` object                                               |
| Integration precondition | Gmail inbox trigger authorization failures                         | `detail.code` and `detail.message`                                     |
| OAuth redirect failure   | MCP server authorization and reauthorization                       | Query parameters on the redirect destination                           |

When `detail.reason` is present, branch on it instead of parsing `detail.message`. Do not assume every error has a reason code or an error-specific details field.

## Authentication and permission

### 401 authentication failures

Missing or rejected credentials return a top-level `error` object rather than the `detail` envelope. It contains `code`, `status`, and `message`.

Mint or refresh the credential once, then retry the request.

### 403 permission failures

Permission checks return `PERMISSION_CHECK_FAILED` with a `permissionCheckFailedError` object describing the subject, resource, and permission.

The message can end with `or it may not exist`. A `403` therefore does not prove that the resource exists: the caller may lack permission, or the identifier may not resolve through the permission check.

### 404 resource failures

Structured resource lookups return `RESOURCE_NOT_FOUND` with a `resourceNotFoundError` object. Other endpoints return a string `detail`, including some file, trigger, integration, and MCP server lookups. Unmatched routes also return a string `detail`.

Treat `403` and `404` according to the endpoint contract. Do not infer resource ownership or existence from the status alone.

## Request validation

Schema validation normally returns `422` with a `detail` array. FastAPI-generated items use `msg`; Rightbrain service validators can use `message`. Read both fields.

Common validation item types include:

| Type                          | Meaning                                                      |
| ----------------------------- | ------------------------------------------------------------ |
| `missing`                     | A required field is absent.                                  |
| `uuid_parsing`                | A body, query, or framework-parsed path value is not a UUID. |
| `int_parsing`, `bool_parsing` | A query or body value cannot be coerced.                     |
| `enum`                        | A value is outside the allowed set.                          |
| `extra_forbidden`             | The endpoint rejects an unknown field.                       |
| `value_error`                 | A cross-field rule failed.                                   |
| `duplicate_task_name`         | A task name is already in use.                               |
| `invalid_llm_model`           | The model ID is invalid or unavailable.                      |
| `invalid_llm_config`          | A model parameter failed validation.                         |
| `invalid_task_prompt`         | The prompt violates a task rule.                             |

Malformed identifiers resolved by application dependencies can instead return `400 MALFORMED_RESOURCE_IDENTIFIER`. Validate UUIDs before sending them, but still handle both statuses.

## Common reason codes

This table is not a complete list. It covers reason codes shared across multiple routes or important execution paths.

| Reason                                 | Default status | Meaning                                                                                       |
| -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `MALFORMED_RESOURCE_IDENTIFIER`        | `400`          | An application-resolved resource identifier has the wrong format.                             |
| `MALFORMED_REQUEST`                    | `400`          | The application could not interpret the request.                                              |
| `PERMISSION_CHECK_FAILED`              | `403`          | The caller lacks the requested permission, or the resource is hidden by the permission check. |
| `RESOURCE_NOT_FOUND`                   | `404`          | A structured resource lookup failed.                                                          |
| `TAG_NAME_CONFLICT`                    | `409`          | A tag name conflicts with an existing tag for that resource type.                             |
| `TASK_USED_BY_ACTIVE_TASK_AGENT_SHARE` | `409`          | An active agent share prevents the task operation.                                            |
| `DATASOURCE_NOT_CONFIGURED`            | `412`          | The required datasource is not enabled.                                                       |
| `TASK_PROMPT_TOO_LARGE`                | `413`          | The assembled prompt exceeds the selected model's context limit.                              |
| `INVALID_TASK_PROMPT`                  | `422`          | The task prompt violates a prompt rule.                                                       |
| `TASK_VALIDATION`                      | `422`          | A task-specific validation rule failed.                                                       |
| `INVALID_LLM_RESPONSE`                 | `500`          | The model output did not satisfy the task's structured output contract.                       |
| `UNEXPECTED_TASK_EXECUTION`            | `500`          | A provider or other unexpected failure interrupted task execution.                            |
| `INTERNAL_ERROR`                       | `5xx`          | The server returned an intentionally generic domain error.                                    |

An endpoint can override a domain error's default status. Use the API reference and the actual HTTP status together with the reason code.

## Integration preconditions

Gmail inbox trigger creation uses `detail.code`, not `detail.reason`, when the integration cannot be used:

| Code                                 | Status | Required action                                    |
| ------------------------------------ | ------ | -------------------------------------------------- |
| `GMAIL_INTEGRATION_AUTH_REQUIRED`    | `409`  | Authorize Gmail for the invoking user.             |
| `GMAIL_INTEGRATION_REAUTH_REQUIRED`  | `409`  | Reauthorize Gmail.                                 |
| `GMAIL_INTEGRATION_AUTH_UNAVAILABLE` | `503`  | The deployment must configure Gmail authorization. |

Other Gmail preconditions use string `detail` values: a missing integration returns `404`, and a non-Gmail or incompatible integration returns `422`.

## MCP OAuth redirects

MCP server authorization is a browser flow:

| Operation                       | Method | Success               | OAuth discovery failure with `redirect_to` |
| ------------------------------- | ------ | --------------------- | ------------------------------------------ |
| Authorize a server URL          | `GET`  | `303` to the provider | `307` to `redirect_to`                     |
| Reauthorize a registered server | `POST` | `303` to the provider | `307` to `redirect_to`                     |

The failure redirect appends `error=oauth_authorization_failed`, `error_description`, and `server_url`. When `redirect_to` is omitted, startup failures return a normal `400` JSON response instead.

The callback is also browser-driven. It uses the secure `oauth_state` cookie from the authorize step rather than bearer authentication and redirects after processing.

## Task and agent runs

Task runs require a top-level `task_input` object. Request parsing and validation failures can occur before execution begins. Billing or credit preconditions return `402`; changing the request without resolving the account state will not make that request succeed.

Agent runs require `message` and return Server-Sent Events after preflight checks pass. Preflight failures are ordinary HTTP errors, even when the request accepts `text/event-stream`. Once a `200` stream is open, run failures arrive as an `error` event.

An `approval_required` event is not a failure. It closes the current stream and leaves the run in `waiting_for_human`. Approving records the decision; call the approval request's `/resume` endpoint to execute the approved tool and continue the run.

## Server errors

A `5xx` response can be:

* Plain text `Internal Server Error` for an unhandled exception.
* JSON with a string `detail`.
* A structured domain error, including `INVALID_LLM_RESPONSE`, `UNEXPECTED_TASK_EXECUTION`, or `INTERNAL_ERROR`.

Check the status and content type before decoding JSON. Do not depend on internal provider text in an execution error remaining stable.

## Retry guidance

* Refresh or replace a credential once after `401`.
* Resolve permission, validation, billing, or integration state before retrying `4xx`.
* Retry `409` only after the conflicting state changes.
* Back off on `429`.
* Retry transient `5xx` failures with a limit and jitter; investigate repeated structured execution failures.

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