I’m building an integration app for Zapier and need help with error handling. When my API can’t find the requested data or encounters issues, I want to send back properly formatted error messages that Zapier can display nicely to users.
Right now I’m just returning a 400 status code with basic text, but the error display looks pretty ugly. I’ve seen other apps like Google Sheets show clean, user-friendly error messages in Zapier.
What’s the correct way to structure the error response object so Zapier formats it properly? I want users to see a clear explanation of what went wrong instead of just raw error text.
zapier expects errors in a specific format. return a 400 status with {\"message\": \"your friendly error text here\"} in the body. avoid generic messages – be clear about what went wrong. use the right status codes, like 404 for not found and 422 for validation errors, so zapier shows the correct error.
I ran into this exact problem building my Zapier integration last year. You need the right HTTP status code AND a clean JSON structure for errors. I use something like {“errors”: [{“message”: “Can’t find contact ID 12345. Check if it exists in your account.”}]} with 404 for missing stuff or 422 for validation errors. Be specific about what broke and tell users what to do next. Zapier’s error display picks up this structure and shows it way cleaner than raw error strings. Skip the generic 500 errors if you can - users can’t tell if they screwed up their setup or if your service is broken.
Use Zapier’s HaltedException format for your error responses. When your API hits an issue, return a JSON object with HTTP status 400 (or whatever’s appropriate) plus an ‘error’ field with a user-friendly message. Like this: {“error”: “The record you’re looking for doesn’t exist. Please check the ID and try again.”}. Keep your error messages conversational and actionable - tell users what went wrong and how to fix it. Zapier will format this into a clean error display instead of showing raw HTTP responses. Make your messages specific enough to help users troubleshoot, but don’t get too technical.