# Errors and what they mean

Source: https://neatlisting.com/docs/errors

> Error messages from NeatListing's MCP server and OAuth endpoints, what causes each one and what an agent should do, including how Google Business Profile API errors are passed through.

[Docs](https://neatlisting.com/docs) · Errors

NeatListing reports problems in three places. HTTP errors on `/mcp` cover sign-in and rate limits. Tool errors come back as an MCP result with `isError: true` and a plain-language message. Listing changes that can't go through come back as a change record with status `blocked` (NeatListing refused it) or `failed` (Google refused it, with Google's own message).

## HTTP errors on /mcp

- `401` with no token: the `WWW-Authenticate` header points at the OAuth metadata. Your client should start sign-in. See [Authentication](https://neatlisting.com/docs/authentication).
- `401` "The access token is invalid or expired.": refresh the token, or sign in again if the refresh fails.
- `401` "This connection was revoked by the owner.": the owner disconnected this agent in the dashboard. Only a new sign-in brings it back.
- `405`: a method other than `POST` with a valid token. The server is stateless and has no GET stream.
- `429` with JSON-RPC error `-32000` "Rate limit: at most 60 requests a minute per agent (the connection handshake doesn't count).": wait for `Retry-After` (60 seconds) and continue.
- `400` with an empty body: the request body wasn't valid JSON.

## Tool errors (isError: true)

These mean the call itself couldn't run. Nothing was changed.

- "Location not found or not in your scope." or "Location not found.": the `location_id` is wrong or not shared with this agent. Call `list_locations` and use a `loc_…` id from it.
- "Change not found.": the `change_id` doesn't exist or belongs to another agent.
- "Change is already applied." (or rejected, failed…): the change isn't waiting anymore. Don't approve or reject it again.
- "Agents can only undo their own changes.": ask the owner to undo it from the Activity page.
- "Only applied profile edits, attributes, menus and review replies can be undone.": posts, photos, links, hotel details, verification and deletes can't be undone.
- "Pass owner_confirmation: the owner's own words approving this change.": `approve_change` needs the owner's actual words.
- "This agent was connected read-only, so it can't change setup." (also for approving or rejecting changes): the owner connected this agent with read access only.
- "No locations connected.": `search_categories` needs at least one location to run under.
- "Too many settings changes this hour (60). Try again later.": too many `set_location_access` changes in an hour.
- Invalid arguments: the input didn't match the tool's schema. The MCP SDK returns which field failed. Check the format in the tool's description.

Reads that reach Google can also return a Google error message as a tool error (see below).

## Blocked changes

Status `blocked`: NeatListing refused the change before calling Google. The `detail` is one of these:

- "This agent was connected read-only."
- "This location is paused by the owner." The owner turned agents off for this location.
- "This agent isn't allowed to edit this location." The owner didn't pick it on the Allow page.
- "NeatListing can't verify an owner or manager role on this profile in Google." The owner's role in Google is missing or couldn't be confirmed. Calling `list_locations` with `refresh: true` re-checks it.
- "This action needs target: the post name (accounts/…/locations/…/localPosts/…)." and similar: pass the resource name.
- "That isn't a … on this location. Use the exact name from the matching list tool." The name you passed belongs to another location or is made up. Copy it from `list_posts`, `list_photos`, `list_action_links`, `list_reviews` or `get_verification_status`.
- A validation message naming the field, for example "periods: Give at least one open period. To close the business, use open_info instead." or "Use a category id like categories/gcid:jewelry_store (see search_categories)." Fix the value and send it again.

## Failed changes and Google's errors

Status `failed`: NeatListing sent the change and Google refused it, so nothing changed. Google's message is passed through in `detail` in this form:

```
Google PATCH /v1/locations/123 failed (400): Request contains an invalid argument. (regular_hours.periods[0].close_time: …)
```

The method, path and HTTP status come first, then Google's message, then the field and reason from Google's error details when it gives them.

- `400`: Google didn't accept the value. The part in brackets usually names the field. Fix it and retry.
- `403`: usually the owner's Google account no longer has permission on this profile. Call `list_locations` with `refresh: true`; if the profile disappears, the owner needs their role back in Google.
- `404`: the post, photo, link or review no longer exists. List again to get current names.
- `429` or `5xx`: Google is busy. Reads are retried twice automatically; writes are not. Wait a minute, check with `get_change` or a read that the change didn't go through, then retry once.

Other messages that start with "Google":

- "Google rate limit: NeatListing paces calls to Google so every customer keeps working. Try again in a minute." NeatListing spends at most 120 Google calls a minute per Google sign-in. Large batches hit this; pause and continue.
- "Google token refresh failed: … The owner may need to sign in again." Google stopped accepting NeatListing's access, often because the owner removed it in their Google account or changed their password. The owner signs in to NeatListing again.
- "Google resource name refused": a name contained characters that can't be part of a Google resource path.
- "This profile has no primary category on Google yet. Set the primary category first." Comes up when setting secondary categories.

"Unexpected error while applying this change. It has been logged." means something failed on NeatListing's side. The team sees these; tell the owner and try again later.

## OAuth endpoint errors

JSON bodies with `error` and `error_description`.

- `invalid_redirect_uri` or `invalid_client_metadata` at `/oauth/register`: check the redirect URI rules and the auth method.
- `slow_down` (`429`): too many registrations or token requests from one address. Wait and retry.
- `invalid_client` (`401`): unknown `client_id` or a wrong client secret. Register again.
- `invalid_grant`: "Code is invalid, expired or already used.", "redirect_uri mismatch.", "PKCE verification failed.", "Refresh token is invalid / expired / revoked / was already used. Reconnect to NeatListing." or "This connection was revoked." All of these end with signing in again.
- `invalid_scope` "Can't widen scope on refresh.": ask only for scopes the token already had.
- `invalid_target`: the `resource` parameter must be `https://app.neatlisting.com/mcp`.
- `unsupported_grant_type`: use `authorization_code` or `refresh_token`.

Problems with the sign-in request itself are shown to the owner on a NeatListing page instead: "This app isn't registered with NeatListing. Ask it to reconnect.", "This app's return address doesn't match its registration.", "PKCE with S256 is required.", "Only response_type=code is supported." or "This approval page expired. Go back to your agent and connect again." (the Allow page lasts 15 minutes).

## Questions

### Why did my change fail when the preview said it would go live?

`preview_change` checks NeatListing's side only. Google can still refuse a value, and then the real change comes back `failed` with Google's reason.

### Should an agent retry a failed change?

Only after reading the reason. Fix the value for a `400`. For a busy error, wait a minute and retry once. Don't retry a `403`; the owner's access needs fixing first.

## More docs

- [NeatListing MCP server docs](https://neatlisting.com/docs)
- [Authentication: OAuth 2.1, registration and tokens](https://neatlisting.com/docs/authentication)
- [Change statuses, history and undo](https://neatlisting.com/docs/change-statuses)
- [High-risk fields](https://neatlisting.com/docs/high-risk-fields)
- [Tool reference: every tool and its inputs](https://neatlisting.com/tools)
