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

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# Errors

> Read HTTP status, the error envelope and actionable conflict details.

<Info>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](/essentials/quickstart).</Info>

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

```json theme={null}
{
  "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](/api-reference/authentication#company-key-scopes) 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](/api-reference/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](/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.


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