Errors

← Reference

What each HTTP status means, the Problem Details fields Monomer returns, and how to act on a role denial. REST errors use application/problem+json; MCP tool calls carry the error inside the tool result, as described in Errors in MCP tool calls.

Status codes

Status	Meaning	What to do
400	The request does not match the contract, for example an unknown field, a missing limit, or an invalid path. Agent APIs also use this status for owner input-value validation.	Fix the request using detail and violations, then send it again.
401	The access token is missing, expired, revoked, or meant for the other audience.	Refresh the token or sign in again. The WWW-Authenticate header points to the protected resource metadata.
403	You can see the target, but your role does not allow this operation.	When the code is ROLE_REQUIRED, ask for the named role; see below.
404	The Organization, Workspace, or resource does not exist, or you cannot access it. Both look the same.	Check the IDs and path you discovered; do not guess another target.
409	The request conflicts with the current state or fails warehouse validation.	For a revision conflict, read the latest current.revision. For PARTITION_FILTER_REQUIRED, add a time range or partition filter before running again.
410	An Explore result download was requested after the result expired.	Run the query again. Results stay available for 3 days.
422	Human REST input values fail owner validation. Agent APIs return 400 for these errors.	Correct the values using detail and violations.
429	Monomer is limiting how often this request can run, for example when sending invitations or signing in.	Wait the number of seconds in Retry-After, then retry.
503	Monomer or a service it depends on is temporarily unavailable.	When retryable is true, wait for Retry-After and retry.
500	An unexpected internal execution error prevented a safe response.	Read the target before resending a create or start request. Quote requestId when reporting the error.

Bearer credentials are verified before request-body decoding. An invalid or expired token returns 401 even when the body is malformed. Resource admission follows decoding. UUID IDs in targets and resource paths must use the canonical lowercase hyphenated form.

Dashboard concurrency codes SESSION_CONFLICT, QUERY_RUN_CONFLICT, DRAFT_CONFLICT, EXECUTION_ADMISSION_CONFLICT, and QUERY_RUN_CANCEL_CONFLICT return 409 with retryable:true. The Workspace run cap returns 503 EXECUTION_BACKPRESSURED with retryable:true across Explore, Dashboard, and Pages. A 503 carries Retry-After: 2 if and only if retryable is true.

Unexpected Agent owner failures use OWNER_UNAVAILABLE. For Dashboard creation, Explore run start, Semantic creation, and unconfirmed Connector changes, a 503 with retryable:false means the change may already have happened. Read or list the target before resending; the server-generated requestId does not make a resend idempotent. These responses and warehouse AUTHENTICATION_FAILED omit Retry-After. AGENT_OWNER_RESPONSE_INVALID identifies an owner response that violates the public response contract. An unexpected owner IllegalArgumentException returns 500 INTERNAL_ERROR. Semantic engine faults also return 500 INTERNAL_ERROR with retryable:false; they do not return a temporary owner outage. If that response violation follows a Dashboard or Semantic create or an Explore start, it also uses retryable:false and asks you to read or list the target before resending, without Retry-After.

Input-validation details preserve the owner’s safe value constraints, Semantic rejection reasons, and missing capability lists. Warehouse and execution exception text stays sanitized.

Semantic query input failures use INVALID_SEMANTIC_QUERY or UNSUPPORTED_SEMANTIC_QUERY with 422 on human REST, and SEMANTIC_QUERY_INVALID or SEMANTIC_QUERY_UNSUPPORTED with 400 on Explore and Semantic check Agent REST and MCP. Ordinary Check findings remain successful check data; a thrown invalid-query or unsupported-capability exception uses the input-error status on Check too. An unsupported engine capability may have a general explanation when Monomer cannot name a narrower capability. Fix the query before resending. Internal rendering and template failures return 500 INTERNAL_ERROR with a safe detail, retryable:false, and no Retry-After. Engine exception text is never a public error detail.

The OAuth endpoints follow OAuth instead: they return a JSON object with an error code, such as invalid_grant, and never say whether a token was valid.

Dashboard commands and cursors

An identical Dashboard Session open, resolve, or refresh command replay returns the stored response after checking your current access. It does not replan queries or start new runs. Changing the input under the same command key returns 409 IDEMPOTENCY_CONFLICT.

If Apply changes the Dashboard definition while a new Session open is being planned, open returns 409 SESSION_CONFLICT and creates no Session or QueryRuns. Read the current Dashboard and submit a new command with a new key.

A Session list cursor belongs to its Dashboard. Use the cursor returned by that Dashboard’s list. A malformed cursor or one from another Dashboard returns an input error: 422 on human and Page reader REST, or 400 CURSOR_INVALID on the agent API.

Problem Details fields

Errors from the agent API follow RFC 9457 Problem Details with Monomer’s own fields. The Problem Details schema is the exact definition.

Field	Present	Meaning
type	Always	A URI for the error code, such as https://monomer.cc/problems/role-required
title	Always	A short summary, such as Editor role required
status	Always	The HTTP status
detail	Always	A sentence you can show to the person you work for
instance	Always	The request path; /mcp for tool calls
code	Always	A stable code in capitals, such as AGENT_REQUEST_INVALID or ROLE_REQUIRED
requestId	Always	The request reference to quote when you contact Monomer
traceId	Always	A trace reference for the same request
retryable	Always	true when the same request can succeed later without changes
violations	When fields are wrong	Each wrong field with its code and message; for patches, also the operationIndex and path when known
current	On a revision conflict	The latest revision to read and retry from
hints	When Monomer can suggest a fix	Short instructions, such as whom to ask for a role
nextActions	When other operations apply	Operations available now, in the same shape a read returns
requiredRole	When known with ROLE_REQUIRED	The role the target needs: VIEWER, EXPLORER, EDITOR, or OWNER in a Workspace, or ADMIN in an Organization
currentRole	When known with ROLE_REQUIRED	The role you hold there now
askOwners	When known with ROLE_REQUIRED	Names of the Workspace Owners you can already see; empty for Organization actions
partitionFilters	With a Semantic PARTITION_FILTER_REQUIRED rejection	Up to 16 source conditions: the Connector, table, partition keys, and, for a model, mapped dimensions and whether a time range can filter them

When a filter comparison type does not match

For a categorical dimension that reads a plain column, a Semantic query filter must use the comparison type from the selected Connector’s current Catalog: TEXT, NUMBER, or BOOLEAN. Computed expressions and column types Monomer cannot map keep the caller’s selected type. A time dimension’s filter type follows the grain the model defines for it: DATE at day or coarser grain and TIMESTAMP at hour or finer grain. Any other type, including TEXT, NUMBER, or BOOLEAN, is rejected the same way; see Time zones and dates.

A mismatch returns 422 INVALID_SEMANTIC_QUERY on human SQL preview or Semantic run start, or 400 INVALID_SEMANTIC_QUERY on Agent run start, with retryable: false. The violation code is QUERY_FILTER_UNRENDERABLE; its field is query.filters[i].kind on human REST and input.query.filters[i].kind on Agent REST and MCP. Correct the filter type before sending a new request. The rejected request creates no run.

When a partition filter is required

BigQuery can require a query to filter a table’s partition column. Semantic start validates SQL before creating an Explore run when the render snapshot reads a table with that requirement. A rejected start returns 409 PARTITION_FILTER_REQUIRED with retryable: false; no run is created.

Use partitionFilters to find the affected model or Calendar table. When timeRangeApplies is true, choose a time range. Otherwise, filter one of the named dimensions. If no dimension maps the partition column, add it to the model first. A Calendar table condition names the table without model dimensions. Check keeps its executable Connectors and reports these conditions separately.

Raw SQL uses the same rejection code and status when BigQuery’s dry run requires a partition filter. Edit the SQL to include that filter before running again.

When a role is missing

An agent acts with its person’s role. When that role is too low for the operation, Monomer answers 403 with code ROLE_REQUIRED. When current role information is available, it names the role the operation needs and the role the person holds, and suggests whom to ask. A later denial or an unavailable role explanation keeps the same code with a safe detail. Pass detail and hints to the person you work for rather than retrying.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://monomer.cc/problems/role-required",
  "title": "Editor role required",
  "status": 403,
  "detail": "Changing a metric in Revenue Analytics needs the Editor role. Sam Kim is an Explorer.",
  "instance": "/v2/workspaces/0198ef28-2000-7000-8000-000000000001/agent/edit",
  "code": "ROLE_REQUIRED",
  "requestId": "srv_0198ef28-3000-7000-8000-000000000003",
  "traceId": "0af7651916cd43dd8448eb211c80319c",
  "retryable": false,
  "hints": ["Ask Mina Park to give Sam Kim the Editor role, then try again."],
  "requiredRole": "EDITOR",
  "currentRole": "EXPLORER",
  "askOwners": ["Mina Park"]
}

askOwners lists only Owners the person can already see in the Workspace. For an Organization action, requiredRole is ADMIN, currentRole is MEMBER, and askOwners is empty because only Admins can see the Admin list; the hint asks an Organization Admin instead. Monomer explains a role only to members of the Workspace: for anyone else, a missing and an inaccessible Workspace both return 404.

Errors in MCP tool calls

A tool call that fails still returns a JSON-RPC result marked with "isError": true. Its text contains the same Problem Details body the REST API returns for that failure, with instance set to /mcp. If monomer_invoke receives a check operation, the first line names monomer_check; if monomer_check receives another action, it names monomer_invoke. For other monomer_create, monomer_edit, and monomer_invoke failures, the text starts with a hint to use monomer_describe to check the operation’s input schema. The Problem’s code, title, detail, status, and retryable still match REST, including for a missing target, a denial without role details, and a temporary failure; a missing and an inaccessible target look the same. When retryable is true for a 503, or the status is 429, the HTTP response also carries Retry-After.

For input failures, review violations and their field locations. Pass entire nextActions entries to monomer_describe as {"operations":[...]} before constructing the next call. An unknown operation combination in describe returns AGENT_REQUEST_INVALID with a location in operations.

A monomer_docs read that fails because the document is missing, too large, or unavailable returns a plain-text explanation. Invalid monomer_docs arguments return AGENT_REQUEST_INVALID like other tools. A missing or expired access token is answered with HTTP 401 and a WWW-Authenticate header, and the client signs in again. A message that is not valid JSON-RPC, names an unknown tool, or has malformed parameters returns a JSON-RPC error instead of a tool result.