Error response structure, common error codes, and tool call error handling for MCP API.
MCP API uses a unified response structure for successful responses and business errors. The response header contains
x-request-id.
Response structure
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. For tool execution, also check data.isError |
| error_code | string / null | Error code. null on success |
| error_msg | string / null | Error message. null on success |
| data | object / array / null | Business data. null on failure |
| request_id | string | Request ID |
Common error codes
| HTTP status | error_code | Description |
|---|---|---|
| 400 | InvalidParameter | A request parameter is missing, malformed, or out of range |
| 400 | OperationNotSupported | The MCP service does not support the operation |
| 403 | AccessDenied | No permission to access the target address or resource |
| 404 | McpServerNotFound | The MCP service does not exist |
| 404 | McpServerUnavailable | The MCP service is deleted or unavailable |
| 409 | McpServerBusy | Another operation is running on the MCP service |
| 409 | McpServerStateConflict | The MCP service state does not allow the operation |
| 409 | McpServerNotActivated | The MCP service is not activated |
| 500 | InternalError | Internal service error |
| 502 | McpUpstreamError | The downstream MCP operation failed |
| 503 | McpUpstreamThrottled | The downstream MCP request was throttled |
| 504 | McpUpstreamTimeout | The downstream MCP request timed out |
Tool call errors
- A failed
tools/callrequest may return400and pass through the MCP serviceerror_codeanderror_msg. - When the tool itself fails, the API may return
200withsuccess=trueanddata.isError=true. Check both the HTTP status anddata.isError. - A failed
toolsrequest may return400or500InternalError.
Troubleshooting
- Use
request_idto locate the request. - Check the API key, workspace ID, and endpoint. See Authentication.
- Make sure the MCP service is activated and its status is enabled.
- Make sure request body field names and types match the API reference.