Errors
Auto reports errors at three levels.
HTTP errors
These come before any tool runs.
| Status | Body | Cause |
|---|---|---|
401 | {"message":"Unauthorized"} | No token, or it expired or was revoked. See the WWW-Authenticate header. |
403 | {"error":"insufficient_scope","error_description":"Missing scope: mcp:images"} | The token lacks the scope. |
405 | JSON-RPC error -32000, Method not allowed. | The request was a GET or DELETE. |
Argument errors
If the arguments don't match a tool's inputSchema, the MCP SDK rejects the call before the tool runs. For example, limit: 500 or an id with a slash.
Some checks span more than one argument, such as "radiusMeters needs latitude and longitude". The tool runs those itself and fails with a message that starts with Invalid parameters:.
Tool errors
A tool that fails returns a normal result with isError: true and one text block. The text is written for the user. Agents can pass it on as is.
{
"isError": true,
"content": [{ "type": "text", "text": "Image not found" }]
}
| When | Message |
|---|---|
| The user has no Auto Photos account | No photos in your Auto Photos account. Install the Auto Photos app from the App Store to start syncing photos: <url> |
| Auto Photos is set up and syncing, but has no photos yet | No photos in your Auto Photos account yet. Auto Photos is still sending photos from your iPhone. Try again in a few minutes. |
| Auto Photos is set up, syncing is off, and there are no photos | No photos in your Auto Photos account. Open the Auto Photos app on your iPhone and turn on syncing to add your photos. |
An album filter or album tool for a user on auto | Albums are part of Auto Photos. ... |
| An id that is missing, deleted, someone else's, or outside the free plan window | Image not found or Album not found |
| A cross-argument check failed | Invalid parameters: ... |
channels with a circle or an album | channels cannot be combined with a radius search. / ... with an album search. |
| Search is down | Text embedding is unavailable. |
get_image_bytes on a picture over 10 MB | A message that the picture is too large |
| The account has 500 albums | An account can hold at most 500 albums. |
| A rename to a title another album has | There is already an album named "<title>". |
| A cover that is not in the album | The cover must be a photo in this album. Add it to the album first. |
| More than 3 feature requests a minute | A message to wait and try again |
Message text can change. Agents should read it, not match on it.