Docs · Errors

Errors and what they mean

Updated 5 min readView as Markdown

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.
  • 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 is free. Connect your Google Business Profile to Claude, ChatGPT or any app that supports MCP.