Errors

The MCP server surfaces the same coded errors as the REST and GraphQL APIs — a given failure produces the same code, message, and HTTP status on every transport.

Tool errors

A tool failure comes back as an MCP CallToolResult with isError: true and a JSON error payload:

{
  "error": {
    "code": "API_KEY_NOT_AUTHORIZED_FOR_LIBRARY",
    "message": "API key not authorized for this library.",
    "status": 404
  }
}

code — the stable, machine-readable failure mode. Dispatch on this.
message — a human-readable string safe to surface to end users.
status — the HTTP status the same error returns over REST, included so clients can reuse REST-oriented error handling.

A failed resource read surfaces as a JSON-RPC error whose message carries the same text as the equivalent tool error. The JSON-RPC error envelope carries the message only; for machine-readable code and status, use the equivalent tool, whose error payload always includes both.

Error-code reference

The set of codes, their messages, and the HTTP status each maps to is shared across transports. Rather than duplicate it here, see the canonical table:

REST error reference

Every error code, its HTTP status, and when it fires.

The codes you'll most often see from MCP tools:

Code	Status	When
`UNAUTHENTICATED`	401	Missing or malformed `Authorization` header.
`INVALID_API_KEY`	401	The bearer token doesn't match a key in the target organization.
`API_KEY_NOT_AUTHORIZED_FOR_LIBRARY`	404	The key can't reach the target library (or it doesn't exist).
`ORGANIZATION_NOT_FOUND`	404	The `organizationId` doesn't resolve to a known org.
`RESOURCE_NOT_FOUND`	404	A referenced asset doesn't exist.
`BAD_USER_INPUT`	400	Invalid arguments — over a cap, a reserved tag, a cross-org transfer.
`PAYLOAD_TOO_LARGE`	413	A file exceeds the per-file size limit.
`INTERNAL_SERVER_ERROR`	500	An unexpected server fault. Safe to retry with backoff.

Tool errors

Resource errors

Error-code reference

REST error reference

On this page