Troubleshoot the Workspaces API, MCP, and Git

Start by checking the API key with GET /v1/me. If the request returns 401, confirm that you sent an active API key as a Bearer token. Create a new key if the old one was revoked.

Check the API first

Follow Check an API key.
Open /v1/openapi.yaml on your Workspaces instance.
Confirm that the file lists the route and method you plan to call.

Do not use a route found only in a product plan or target API design.

Fix API errors

Result	Recovery
`400`	For `reserved_path`, choose a path outside the reserved `refs/` namespace.
`401`	Send an active Workspaces API key as a Bearer token. Create a new key if the old one was revoked.
`403`	Confirm that the key owner can make the change. Workspaces also blocks changes to organization workspaces when it reports the organization as expired.
`404`	Check the served OpenAPI file, route, workspace ID, and document ID. Workspaces also returns `404` when the key cannot view a private resource.
`409`	For `path_conflict`, choose another path or remove the existing item. For `annotation_resolved`, reopen the comment before replying.
`412`	Read the latest document body, apply your change again, and send its version in `If-Match`.
`413`	For `artifact_too_large`, publish a file no larger than 100 MiB. For `quota_exceeded`, stop retrying. Retained history counts toward quota, and only deleting a whole workspace frees it. Ask the workspace owner before deleting anything.
`422`	Compare the request with the served schema and correct the named fields.
`429`	Wait for the number of seconds in `Retry-After`, then retry.

Fix MCP connections

Use Streamable HTTP with POST /mcp. Send the API key in the Authorization header.

Result	Recovery
`400` with an unsupported protocol version	Update the MCP client or choose a protocol version that the instance supports.
`401 Unauthorized`	Send an active API key as a Bearer token. Check the `Authorization` header format, and create a new key if the old one was revoked.
`403 Invalid Origin header`	If the client can omit `Origin`, omit it. Otherwise, send an origin whose scheme, host, and port match `APP_ORIGIN`. Local and development instances also allow the request’s own origin and loopback origins. Set `APP_ORIGIN` to the Workspaces app URL, not the agent URL.
`405` for `GET` or `DELETE`	Set the client to Streamable HTTP. Do not open `/mcp` as a browser page.
A tool is missing	Reconnect, then use the tool list and schemas returned by the server. Do not infer tools from the REST API.
A tool returns an access error	Confirm that the key owner can open the workspace and make the requested change. For `billing_expired`, follow Trials and billing.

See Connect an agent to Workspaces with MCP for the connection fields and current tools.

Fix Git clone and fetch

Workspaces Git requires an account and API key. Enter any username and use the API key as the password.

Result	Recovery
The authentication prompt repeats or returns `401`	Create an API key and use it as the Git password. A share token cannot authenticate Git.
`No such workspace Git repository`	Check the workspace ID and confirm that the key owner can view it.
`No checkpointed Git repository exists for this workspace`	Save a document change and retry. Ask the instance admin to check the Git store if the error continues.
`500` with a Git service failure	Retry once. If it fails again, ask the container admin to check the Git service and logs.
`502` with a Git service failure	Retry once. If it fails again, ask the Cloudflare admin to check the repository settings and Artifacts connection.
`503` with a busy message	Wait and retry. The container has reached its Git process limit.
`503` with a not-configured message	Ask the Cloudflare admin to configure the Git service.
Push returns `405`	Make the change in the browser or through the API or MCP. Workspaces Git is read-only.

See Clone a workspace with Git for the clone URL and read-only limits. Reviewed July 20, 2026. Maintained by the Plannotator documentation team.

Start

Accounts and organizations

Sharing and access

Documents and collaboration

Agents and developer access

Plans, billing, and seats

Self-hosting and updates

Security and privacy

Troubleshooting

Troubleshoot the Workspaces API, MCP, and Git

Check the API first

Fix API errors

Fix MCP connections

Fix Git clone and fetch

​Check the API first

​Fix API errors

​Fix MCP connections

​Fix Git clone and fetch

Check the API first

Fix API errors

Fix MCP connections

Fix Git clone and fetch