MCP Error Codes

The Bigdata MCP server reports failures in two different ways, depending on where the failure happens. Authentication, access, and generic server problems come back as HTTP error responses. Problems that occur while a tool is validating or running its request come back as HTTP 200 with an error flag inside the response.

HTTP error codes

If there is an issue with authentication, access, or a generic server error, the MCP server returns one of the following:

HTTP status	Details	Suggested action
401	Re-authentication required.	The client should automatically try the OAuth flow to authenticate.
403	Forbidden access to a service or resource.	Verify your credentials. If they are correctly provided, email [e-mail] to revise your entitlements.
500	An unexpected error occurred.	Please try again later.

Tool errors

If a tool responds but there was an error during validation or execution, the server returns HTTP 200 Success with the response parameter isError set to true. The explanation for the user is in the text content block.

The following example shows a user who has run out of credits, so the tool could not return data:

event: message
data: {
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "request_id: af5b4056-11c4-4ffb-9fa5-dc23414c017b\n\nYou've used up your credits.\n\nIndividual: [Top up](https://app.bigdata.com/billing?utm_source=claude.ai) with credits and resume instantly — pay only for what you use.\n\nTeams & organizations: [Request enterprise access](https://bigdata.com/get-mcp) to expand your quota.\n\n"
      }
    ],
    "isError": true
  }
}

Once the \n escapes are resolved, the text field reads as follows:

request_id: af5b4056-11c4-4ffb-9fa5-dc23414c017b

You've used up your credits.

Individual: [Top up](https://app.bigdata.com/billing?utm_source=claude.ai) with credits and resume instantly — pay only for what you use.

Teams & organizations: [Request enterprise access](https://bigdata.com/get-mcp) to expand your quota.

Search rate limit

If the assistant sends too many searches at once or in a short time, a search tool returns a tool error saying that the search rate limit was reached and how many seconds to wait. This is temporary and is not a credits problem. Wait that long, then ask the assistant to run searches one or two at a time instead of many in parallel. See Rate limits.

At the moment we do not support error codes in tool responses. Please email [e-mail] if you require it for your use case and we will start providing errors to satisfy them.