Errors

Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see Get started.

Most REST failures return a JSON object with error. Some add code and contextual fields.

{
  "error": "this API key belongs to a different workspace",
  "code": "workspace_key_scope"
}

The example shows a company-key scope error. Use status and code to handle the error category; the English message supplies diagnostic context.

Status	Meaning	Client action
`400`	Invalid input	Correct the request before retrying.
`401`	Missing or invalid authentication	Obtain the right credential.
`403`	Company, actor or resource access denied	Check membership and credential scope.
`404`	Missing or inaccessible resource	Check the identifier and selected company.
`409`	Conflicting state	Read the conflict details and current resource.
`413`	Body or attachment too large	Reduce the input.
`422`	A submitted configuration was rejected	Follow the returned explanation.
`429`	Rate limit reached	Respect `Retry-After` when supplied.
`500` / `503`	Server failure or unavailable dependency	Retry only when the operation is safe to repeat.

Company key scope

403 workspace_key_scope is deliberately shared by a key targeting another company, a route outside the key allowlist, and a route requiring admin scope when the key has tasks scope. The code identifies the credential boundary, not a unique cause. The scope tables and the company attached to the key tell you what to check. Messages can distinguish these cases for a person; clients should not branch on their exact wording or retry an unchanged forbidden request.

A saved definition may not be active

Company definition edits can be saved but fail to apply immediately. A 409 can describe this state. Keep any returned operation or commit identifier and inspect the resource before trying to save the same change again. Idempotency covers supported retry keys.

OAuth and MCP

OAuth errors use error and error_description. For MCP JSON-RPC and tool-result failures, follow MCP results, including how to inspect errors inside an HTTP success response.

Task and scope codes

Status / code	Meaning and next step
`403 agents_only`	This operation requires an Agents company, including API-key creation and Area writes. Use an existing invited company.
`400 task_mcp_servers_invalid`	Fix the named MCP configuration field; error text does not expose its value.
`403 task_mcp_servers_forbidden`	The caller cannot configure Task MCP servers. Use an authorized owner/admin or company key.
`409 client_request_conflict`	The retry ID was reused with changed input. Restore the original payload or create a new ID for new work.
`403 isolated_task_scope`	A Run tried to act outside its isolated Task’s permitted operations.
`409 active_duplicate_task`	An equivalent open Task exists. Read the returned Task before deciding whether another is intended.

A funding conflict can return 409 with the literal message requested execution funding is unavailable, without a dedicated code. Inspect the execution identity’s permitted funding and capacity. Clients must allow errors with no code and avoid depending on English message text.

Get started

Conventions

Endpoints

Company key scope

A saved definition may not be active

OAuth and MCP

Task and scope codes

​Company key scope

​A saved definition may not be active

​OAuth and MCP

​Task and scope codes

Company key scope

A saved definition may not be active

OAuth and MCP

Task and scope codes