# API Errors in ZazzyAgent Flow Builder: Troubleshooting Guide An API-powered automation introduces another system into your workflow. That means there are now more places where something can go wrong. Your Flow may be correct while the external API is returning an error. Or the API may work while ZazzyAgent is mapping the response incorrectly. The fastest way to troubleshoot is to identify exactly where the failure occurs. ## The complete API path Think of the workflow as: ```text Flow ↓ Request ↓ Authentication ↓ External API ↓ Response ↓ Response Mapping ↓ Next Flow Step ``` Check each layer separately. ## Problem 1: API verification fails If the API cannot be verified while setting it up, check: * Endpoint * HTTP method * Authentication * Request parameters * Required headers * Request body The current API workflow validates the integration before saving it and reports errors when verification fails. ## Problem 2: Authentication error Common symptoms include: > 401 Unauthorized or: > 403 Forbidden Check your: * API key * Bearer token * Authentication header * Account permissions * Credential status Make sure the credential belongs to the correct external system. ## Problem 3: Wrong HTTP method Your external API may require: **POST** while your ZazzyAgent configuration uses: **GET** Check the external API documentation. ## Problem 4: Missing parameter Suppose the API requires: ```text order_id ``` but your request sends: ```text phone ``` The API can reject the request. Check every required parameter. ## Problem 5: Dynamic value isn't being sent Your API may depend on customer information collected earlier. For example: > Customer enters order number. If that value isn't mapped into the API request, the API won't know which order to look up. Check: **User Input** → **Saved Field** → **API Request** ## Problem 6: API returns an error Your external system may return: ```json { "error": "Order not found" } ``` Don't display the raw error to the customer. Create a customer-friendly fallback. For example: > I couldn't find that order number. Please check the number and try again. ## Problem 7: API returns no data The API may successfully respond but contain an empty result. Example: ```json { "appointments": [] } ``` Your automation needs an appropriate path: > No appointments are available for that date. Please choose another date. ## Problem 8: API response mapping fails The API may return: ```text order_status ``` while your mapping expects: ```text status ``` The API worked. The mapping did not. Check the exact response structure. ## Problem 9: Dynamic list is empty If you're using an API-powered dynamic list, inspect the data at every step. Check: 1. API returned data. 2. Data was captured. 3. Custom field contains the response. 4. JSON structure is correct. 5. List mapping matches the response. 6. List is connected to the active branch. ## Problem 10: API works in testing but fails in the live flow This usually indicates that the live request is different from your test request. Check: * Dynamic values * Customer data * Request parameters * Authentication * Headers * URL variables ## Problem 11: API takes too long An external system may be slow. Don't assume a fixed Delay solves an API timeout. A Delay only waits. It does not make a failed API request succeed. The API itself needs to respond correctly within the available execution time. ## Problem 12: API returns unexpected data A third-party API may change its response structure. For example: Old: ```text status ``` New: ```text order_status ``` Your mapping can stop working even though the API endpoint still responds. Check the current response whenever an integration suddenly stops working. ## Problem 13: Wrong customer data is returned Check which customer information is being used in the request. For example, if the API request accidentally uses a static order number, every customer could receive the same result. Dynamic values should come from the appropriate customer input or stored field. ## Problem 14: API works but customer receives no reply The API step may be successful while the next Flow node isn't connected correctly. Check: **API** → **Response** → **Next message** Also verify conditions between those steps. ## Problem 15: Don't expose technical errors Avoid sending customers: > HTTP 500 Internal Server Error Instead say: > We couldn't retrieve that information right now. Please try again or contact support. Technical details belong in logs/debugging, not customer-facing replies. ## Build a fallback path A reliable API workflow should include a failure strategy. For example: ```text API Call ↓ Successful? ↙ ↘ Yes No ↓ ↓ Continue Friendly Error Message ``` ## Test failure scenarios Don't test only the happy path. Test: * Valid input * Invalid input * Missing input * API error * Empty response * Expired authentication * Wrong response structure ## Use logs when available When debugging a webhook/API workflow, inspect the relevant logs and payload information available in ZazzyAgent. The current workflow documentation specifically recommends checking webhook logs for receipt, timestamps, payloads and failures. ## A useful debugging order Always work from left to right: **Did the Flow run?** ↓ **Was the API called?** ↓ **Was the request correct?** ↓ **Did the external system respond?** ↓ **Was the response correct?** ↓ **Was it mapped?** ↓ **Did the next Flow step run?** This prevents guessing. ## The key rule When an API-powered automation breaks: > **Don't troubleshoot the whole flow at once.** Find the exact point where the data stopped moving. That is usually where the problem is.