IT Management Remote MCP errors and limits

IT Management Remote MCP returns two kinds of errors: HTTP errors and tool execution errors.

If the authentication headers or the request format are wrong, the server returns an HTTP error before MCP processing
If a tool argument or the IT Management API call fails, the server returns the error as the tool result

Error response format

HTTP errors

The server returns JSON with error (the error identifier) and message (the description).

{
  "error": "unauthorized",
  "message": "Missing X-Admina-Organization-Id header."
}

Tool execution errors

The HTTP status stays 200, and the tool result has isError: true. The content text holds the error details.

{
  "content": [
    {
      "type": "text",
      "text": "Invalid input:\nidentityIds: Array must contain at most 50 element(s)"
    }
  ],
  "isError": true
}

HTTP status codes

Status code	`error`	Common cause
400	`invalid_organization_id`	The `X-Admina-Organization-Id` value contains characters other than letters, digits, `_`, and `-`, or is longer than 64 characters
400	`invalid_json`	The request body is not valid JSON
401	`unauthorized`	The `Authorization` header is not in the `Bearer <API_KEY>` format, or the `X-Admina-Organization-Id` header is missing
404	`not_found`	The request went to a path that does not exist
405	`method_not_allowed`	The request used a method other than `POST`
413	`payload_too_large`	The request body exceeds 1 MB
429	—	The request count exceeded the limit (see Limits)
500	`internal_error`	An error occurred inside the server

The load balancer rejects a request without the Authorization header before it reaches the server. This 401 comes back as the plain text 401: Missing Authorization bearer token., not as JSON. A 429 response also comes back as plain text, not as JSON.

Common errors

The beginning of the text tells you the kind of tool execution error.

Text begins with	Meaning
`Invalid input:`	The arguments do not match the input schema (`inputSchema`). The following lines name each problem argument and the reason
`Admina API error:`	The IT Management API returned an error. The error identifier (`errorId`) follows, and `Details:` follows when details exist
`Unknown tool:`	The tool name does not exist
`Error:`	Any other error

The main errors that come back as Admina API error: are the following.

Common cause	Error identifier
The API key is invalid, the organization ID does not match the API key’s organization, or the organization is not active	An IT Management API authentication error
The user who created the API key was removed from the organization	`api_key_creator_removed`
The tool belongs to a feature that is not enabled for your organization	`im_a_teapot`

The tool list also shows tools for features that are not enabled for your organization. Calling one of those tools returns Admina API error: im_a_teapot.

Handling errors

For 401 or an authentication error, go through the checks in Support
For Invalid input:, fix the arguments shown in the message to match the input schema
For 429, wait a while and try again
For 413, send less data at once. For tools that process items in bulk, split the items across calls

Limits

Target	Limit
Request count	Up to 600 requests per minute for each IP address
Request body size	Up to 1 MB
`identityIds` for `bulk_update_identities`	Up to 50
`merges` and `identityMerges` for `merge_identities`	Up to 50 each
`peopleIds` and `identityIds` for `unmerge_identities`	Up to 50 each
`create`, `update`, and `delete` for `save_custom_accounts`	Up to 200 in total

Tools call the IT Management API internally with the API key that you connected with. As a result, the IT Management API rate limits also apply. The requests that tools send count the same way as calls that you make to the IT Management API directly. A single tool call can send more than one request. For example, merge_identities with identityMerges sends extra requests to look up the employee IDs.

When you exceed a limit

If you exceed the per-minute request count, the server returns HTTP status 429 with the text 429: Too many requests.. If you exceed the IT Management API rate limits, the tool returns a tool execution error (Admina API error:).

Staying within the limits

For list tools, use limit to adjust the number of items per call, and fetch only the pages you need
To apply the same update to more than one employee, use bulk_update_identities instead of repeating update_identity
When you check the result of an asynchronous tool, leave an interval between checks

Get started

Guides

Help

Reference

IT Management Remote MCP errors and limits

Error response format

HTTP errors

Tool execution errors

HTTP status codes

Common errors

Handling errors

Limits

When you exceed a limit

Staying within the limits

​Error response format

​HTTP errors

​Tool execution errors

​HTTP status codes

​Common errors

​Handling errors

​Limits

​When you exceed a limit

​Staying within the limits

​Related pages

Error response format

HTTP errors

Tool execution errors

HTTP status codes

Common errors

Handling errors

Limits

When you exceed a limit

Staying within the limits

Related pages