# Errors and limits

Handle Embedded MCP HTTP errors, tool errors, rate limits, expired result sets, and safe retries.

Check where the error occurred before retrying. HTTP errors happen before a tool runs. Tool errors return an MCP result with `isError: true`.

## HTTP errors

| Status | Code | Next step |
| --- | --- | --- |
| 401 | No code | Check the API key and service health. A key lookup failure can also return 401. Do not create another end user. |
| 403 | `EMBEDDED_NOT_ENABLED` | Enable MindCloud Embedded for the organization. |
| 403 | `EMBEDDED_MCP_NOT_ENABLED` | Turn on the Embedded MCP server switch. |
| 403 | `COMPANY_SCOPE_MISMATCH` | Remove a conflicting `X-Company-Id` header. |
| 403 | `API_KEY_ACCESS_DENIED` | Use a key with the required access level. |
| 404 | `END_USER_NOT_FOUND` | Check the stored ID and key's organization before creating a new end user. |
| 429 | `RATE_LIMITED` | Wait before another request. |
| 421 or 503 | Region or authorization unavailable | Use the correct region or retry after service recovery. |
| 503 | `END_USER_LOOKUP_UNAVAILABLE` | Retry after the end-user lookup service recovers. |
| 500 | JSON-RPC `-32603` | Retry after MCP server recovery. |

`GET` and `DELETE` on the MCP URL return 405. Send `POST` requests. The endpoint allows 600 requests per minute per API key.

## Tool errors

```json
{
  "success": false,
  "error": {
    "code": "NOT_CONNECTED",
    "message": "...",
    "nextStep": "get-connect-url",
    "retryable": false
  }
}
```

| Code | Next step |
| --- | --- |
| `APP_NOT_FOUND` | Search apps again. |
| `ACTION_NOT_FOUND` | Search that app's actions again. |
| `NOT_CONNECTED` | Create a connect link for this end user. |
| `CONNECTION_INVALID` | Pass the named `connectionId` to `get-connect-url` to repair it. |
| `CONNECTION_CHOICE_REQUIRED` | Ask the user to choose a connection; pass its ID as `connectionRef`. |
| `CONNECTION_NOT_FOUND` | List the end user's connections again. |
| `RESULT_SET_NOT_FOUND` | Run the original action again if the result expired. |
| `VALIDATION_ERROR` | Match arguments and query controls to the action schema. |
| `MCP_ACTION_EXECUTE_FAILED` | Inspect the provider status and message in the error detail. |
| `RATE_LIMITED` | Wait before creating another connect link. |
| `TEMPORARILY_UNAVAILABLE` | Retry after the dependency recovers. |

An `idempotencyKey` reused with different input can return `MCP_IDEMPOTENCY_CONFLICT`. A call still running with that key can return `MCP_IDEMPOTENCY_LOCKED`. Keep the same key only when retrying the same write.

Input schema errors and unknown tool names can return plain text without an error code. Read the tool's input schema and correct the call. Do not treat a missing connection as an empty response from a failed dependency.