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
Errors from tool execution are returned as a successful JSON-RPC response whose tool result has isError: true and a text message. JSON-RPC errors are reserved for protocol-level problems.
Error Type | Example Message | When It Occurs |
|---|---|---|
Argument Schema Error | validating "arguments": ... | A required argument is missing, or an argument has the wrong type |
Parameter Missing | "Validation error: Required input parameter {param} was missing" | A required argument is empty |
Parameter Format Error | "Validation error: Input parameter {param} must be {requirement}" | An argument has the wrong format, e.g. a ZIP code that is not 5 digits |
Terms Not Accepted | "Terms of Use / Privacy Policy not accepted. ..." | A preset job payment or booking call without termsAccepted: true |
Authentication Error | "Authentication error: Unable to authenticate with Thumbtack, please visit thumbtack.com" | The token is valid, but the partner's client is not fully configured at Thumbtack |
API Error | "Thumbtack couldn't process your request, please visit thumbtack.com: {details}" | A Thumbtack backend error |
For preset job tools, and for filter_home_service_pros when it updates a search, API errors include the backend's message, any field-level errors, and [HTTP {status}, traceID {id}]. Include the traceID when you report a problem to Thumbtack.
Note: "We couldn't find a matching service category" and "No professionals were found" are not errors — they are successful responses indicating empty results. See Troubleshooting for guidance on these cases.
Code | Meaning |
|---|---|
200 OK | Successful MCP response (check the tool result's isError for tool-level errors) |
400 Bad Request | Malformed request, an Accept header that doesn't list both application/json and text/event-stream, or a token that could not be verified on a non-tool call (body: "no server available") |
401 Unauthorized | No token was sent, or the token on a tools/call request is invalid or expired |
403 Forbidden | The token is valid but is missing a required scope |
404 Not Found | Invalid endpoint |
405 Method Not Allowed | A method other than POST on /mcp |
415 Unsupported Media Type | Content-Type is not application/json |
Last Updated: Oct 21st, 2026