--- name: zapier-troubleshooting-router description: > Use when troubleshooting a Zapier error, including McpAuthorizationError, MCP tools missing or returning 404, SDK login failures, expired connections, client credentials not working, an action or trigger timeout, a payload size limit, a 429 rate limit throttle, "an array is expected", an error code from White Label or Trigger Inbox, or an error from the Powered by Zapier API. Routes each symptom to the matching documentation page. license: MIT compatibility: > Applies to docs.zapier.com public documentation. metadata: author: zapier --- # Zapier troubleshooting router This skill maps a symptom to the page that explains it. Match the exact error text or code when you can. ## Critical rules - **Route, do not diagnose:** Point to the page. Do not guess a cause the page does not state. - **Check the context:** Integration limits differ between Zap editor testing, turning a Zap on, and Zap runs. Read the constraint on the page for the context that failed. - **MCP 404 errors:** They affect only MCP clients that store a connection token. ## Symptom to page | Symptom | Read | |---|---| | `McpAuthorizationError` | [Authorization error](https://docs.zapier.com/mcp/troubleshoot/authorization-error) | | Browser sign-in completes, but the MCP client does not connect | [Sign-in not completing](https://docs.zapier.com/mcp/troubleshoot/sign-in-not-completing) | | MCP connection times out | [Connection times out](https://docs.zapier.com/mcp/troubleshoot/connection-times-out) | | MCP tools missing in the client | [Tools missing in client](https://docs.zapier.com/mcp/troubleshoot/tools-missing-in-client) | | MCP tools return 404, or work once and then fail | [Tools return 404](https://docs.zapier.com/mcp/troubleshoot/tools-return-404), [Tools fail after first call](https://docs.zapier.com/mcp/troubleshoot/tools-fail-after-first-call) | | MCP tool call fails with no error message, or one app stops working | [No error message](https://docs.zapier.com/mcp/troubleshoot/tool-call-no-error), [App connection issue](https://docs.zapier.com/mcp/troubleshoot/app-connection-issue) | | Action or trigger times out (30 seconds) | [Action timeouts](https://docs.zapier.com/integrations/build/troubleshoot-action-timeouts), [Trigger timeouts](https://docs.zapier.com/integrations/build/troubleshoot-trigger-timeouts) | | Payload too large (20 MB response in testing, 6 MB action input in runs) | [Action payload](https://docs.zapier.com/integrations/build/troubleshoot-action-payload), [Trigger payload](https://docs.zapier.com/integrations/build/troubleshoot-trigger-payload) | | 429 errors, throttling, or too many requests to your API | [Throttles](https://docs.zapier.com/integrations/build/troubleshoot-throttles), [Reduce requests](https://docs.zapier.com/integrations/build/reduce-api-requests) | | "An array is expected" | [Array expected](https://docs.zapier.com/integrations/build/error-array-expected) | | "Got a non-object result, expected an object" or "non-object result in the array" (REST Hook trigger) | [Non-object result](https://docs.zapier.com/integrations/build/error-non-object), [Non-object array](https://docs.zapier.com/integrations/build/error-non-object-array) | | "Cannot retrieve app" | [Cannot retrieve app](https://docs.zapier.com/integrations/build/error-cannot-retrieve-app) | | Custom field limits or file dehydration limits | [Custom fields](https://docs.zapier.com/integrations/build/troubleshoot-custom-fields), [Hydration limits](https://docs.zapier.com/integrations/build/hydration-limits) | | Any other run-time limit | [Operating constraints](https://docs.zapier.com/integrations/build/operating-constraints) | | Your API returns a status code above 400 that should not stop the step, or you are choosing how to handle error responses | [Add error response handling](https://docs.zapier.com/integrations/build/errors), [Error handling](https://docs.zapier.com/integrations/manage/error-handling) | | Your API is down and Zaps are turning off, or OAuth token refresh returns 4xx | [API outage](https://docs.zapier.com/integrations/manage/api-outage), [Token refresh 4xx errors](https://docs.zapier.com/integrations/news/2025/4xx-errors-refreshAccessToken) | | Integration testing fails (`invoke`, unit tests, or Platform UI testing) | [Testing and debugging](https://docs.zapier.com/integrations/build-cli/testing-and-debugging), [Test and monitor](https://docs.zapier.com/integrations/build/test-monitoring) | | White Label connection flow, token exchange, or token refresh error codes | [White Label error handling](https://docs.zapier.com/white-label/implementation/error-handling) | | Connections API errors, or a connection webhook delivery | [Connection webhooks errors](https://docs.zapier.com/white-label/connection-webhooks/error-handling) | | Trigger Inbox error codes or unexpected behavior | [Trigger Inbox errors](https://docs.zapier.com/white-label/trigger-inbox/errors) | | Powered by Zapier API error format or 429 rate limit | [API errors](https://docs.zapier.com/powered-by-zapier/api-reference/common-types/errors), [Rate limiting](https://docs.zapier.com/powered-by-zapier/api-reference/rate-limiting) | | `zapier-sdk login` or `zapier-sdk signup` fails, the browser does not open, or the CLI hangs | [SDK CLI](https://docs.zapier.com/sdk/using-the-cli) | | `find-first-connection` returns nothing, or a connection shows `isExpired: true` | [SDK CLI](https://docs.zapier.com/sdk/using-the-cli) | | Client credentials not working, or `ZAPIER_CREDENTIALS_CLIENT_ID` / `ZAPIER_CREDENTIALS_CLIENT_SECRET` not picked up by `createZapierSdk()` | [Deploy with client credentials](https://docs.zapier.com/sdk/deploy) | ## Canonical documentation - [Get help with the Zapier Developer Platform](https://docs.zapier.com/integrations/quickstart/get-help): support channels, including Zapier Support for a failing Zap ## Related skills - For MCP concepts, use `zapier-mcp-guide`. - For building integrations, use `zapier-integrations-guide`. - For White Label and Powered by Zapier, use `zapier-embed-guide`.