Overview
Getting Started
MARKETPLACE
Widgets
MCP Server
Find Pros
Categories
Keywords
Requests
Leads
Messages
On-Demand Orders
Reviews
User Accounts
Testing Your Marketplace Integration
PRO INTEGRATIONS
Leads
Messages
Reviews
Pro Profiles
Business Phone Numbers
Manage Webhooks
Testing Your Pro Integration
Support
Changelog
Terms and Policies
This page helps diagnose and resolve the most common issues users and integrators may encounter.
What happened: The search returned zero results for the given category and location.
Possible causes:
- The ZIP code is in a rural or low-coverage area where few pros are registered.
- The service category has limited supply in that region.
What the user should do:
- Try a neighboring ZIP code or a nearby city's ZIP code.
- Check the relevantCategories field in the response — a related category may have better coverage.
- Use the searchThumbtackURL in the response, or visit thumbtack.com directly to browse available pros.
What happened: The user's query did not match any of Thumbtack's service categories.
Possible causes:
- The query is too vague (e.g., "fix stuff").
- The service requested is not offered on Thumbtack (e.g., "dentist", "grocery delivery").
- The query describes something that is not a home service.
What the user should do:
- Try a more specific description (e.g., "kitchen faucet repair" instead of "fix things").
- Ask for category recommendations using get_category_recommendations to see what's available.
- Browse categories at thumbtack.com/more-services.
What happened: The access token was accepted, but the partner's OAuth client is missing configuration that Thumbtack sets up during onboarding.
What the partner should do:
- Contact Thumbtack to verify your client configuration. Retrying will not help until it is fixed.
What happened: The request was rejected before reaching any MCP tools.
Possible causes:
- No Authorization: Bearer header was sent. Discovery calls such as initialize and tools/list need the token too.
- The access token expired. Request a new one.
- The token was minted for the wrong environment (a staging token sent to production, or the reverse), or without audience=urn:partner-api.
- Your integration is identified by IP allowlist, and the request came from an IP address that Thumbtack has not registered.
- 403: the token is missing one of the four required scopes.
An expired or invalid token is rejected with 401 only on tools/call. On discovery calls such as initialize the server cannot tell which partner sent the request, so it returns 400 Bad Request with the body "no server available" instead.
What the partner should do:
- Request a new token with the audience and scopes listed in Connect and Authenticate, and send it on every request.
- If you use IP allowlisting and your egress IP addresses changed, ask Thumbtack to update the allowlist.
- If the problem persists, contact Thumbtack to confirm your client's scopes.
What happened: An internal error occurred when calling Thumbtack's backend APIs.
Possible causes:
- Temporary service disruption or high load.
- An unexpected input combination that the backend could not handle. For preset job tools, the message includes the details.
What the user should do:
- Wait a moment and try the request again.
- If the issue persists, visit thumbtack.com directly to complete the search. Partners reporting the issue should include the traceID from the message, if present.
"Validation error: Required input parameter zipCode was missing" or "Input parameter zipCode must be 5 digits"
All tools that take a ZIP code require a 5-digit US ZIP code. The server does not infer the user's location.
What the assistant should do:
- Ask the user for their ZIP code, and use the ZIP code the user provided in later tool calls. Never use a placeholder or assumed ZIP code.
What happened: After searching, no clarifying questions were shown.
Possible causes:
- Only 0 or 1 professional was found. The server only returns the request form when 2 or more pros are found (since filtering is not useful with fewer results).
What the user should do:
- This is expected behavior. If more than one pro is found, questions will appear automatically.
What happened: The professionals or reviews shown differ from what the user sees on the Thumbtack website.
Possible causes:
- The MCP Server returns up to 6 pros per search, and the widget shows the first 3, while thumbtack.com may show more.
- Search results can vary slightly based on the API parameters used.
- Pro availability and ratings change in real time.
What the user should do:
- Click on the servicePageURL links to see the most up-to-date information on Thumbtack.
- Use the seeMoreProsURL link for a broader list on Thumbtack.com.
Last Updated: Oct 21st, 2026
On this page