# Errors (/docs/api/errors)

Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, `Content-Type: application/problem+json`, never cached:

```json
{
	"type": "https://media.obelism.studio/docs/api/errors#unknown_space",
	"title": "The space could not be resolved in this organization.",
	"status": 404,
	"code": "unknown_space",
	"detail": "No space with this id in the organization that you may open.",
	"hint": "List the organization’s spaces first (listSpaces)."
}
```

Branch on `code`; `detail` and `hint` are for people and may change. Through MCP, a failed tool call returns the same JSON as its text.

### invalid_request [#invalid_request]

**400**: Fix what `detail` names: a body that isn't a JSON object, a field of the wrong shape, a URL that isn't `https` or points at a private host, more than 20 tags.

### unauthorized [#unauthorized]

**401**: Send a valid bearer token: a session token from www for the agent API, an OAuth access token for `/mcp`. Sign in again when it expired.

### forbidden [#forbidden]

**403**: Changing files takes an admin, developer or editor role in the Space. Ask an admin of the Organization.

### unknown_organization [#unknown_organization]

**404**: Check `organizationId`: list your Organizations first (`listOrganizations`).

### unknown_space [#unknown_space]

**404**: Check `spaceId`: it must be a Space of the Organization you may open (`listSpaces`).

### not_found [#not_found]

**404**: No file or folder with this id in the Space, or no endpoint at this path.

### method_not_allowed [#method_not_allowed]

**405**: The endpoint exists, but not for this HTTP method. Check the method in the [OpenAPI spec](/openapi.json).

### conflict [#conflict]

**409**: The change clashes with what is there: a folder that still holds folders or files, a folder name its siblings already have, a folder moved inside itself.

### too_large [#too_large]

**413**: The file is larger than this way of adding one takes (50 MB from a URL). Upload it in the library instead.

### rate_limited [#rate_limited]

**429**: More than 300 calls in a minute. Wait for `Retry-After` before sending more.

### internal_error [#internal_error]

**500**: Something broke on our side. Retry later.