Error reference | Rightbrain Docs — Build reliable AI agents

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.