If you are experiencing issues with your webhook setup, this guide provides an overview of common error messages returned by the destination system (for example, your own server or a third-party service), along with recommended troubleshooting steps.
❗ Please note that these errors do not originate from Heyflow; they are generated by the configured webhook endpoint. It is therefore important to review the logic of your external server in order to accurately identify the cause of the error triggered by incoming HTTP requests from Heyflow.
🔎 For an overview of the error codes, take a look here.
General recommendations
Ensure URLs and endpoints are spelled correctly and accessible.
Use webhook testing tools during development.
Monitor for DNS or connectivity issues, especially with services hosted externally.
Implement error logging with Response IDs to trace issues quickly.
getaddrinfo EAI_AGAIN / getaddrinfo ENOTFOUND
Description: DNS resolution error. This typically indicates a temporary failure in resolving the domain name.
Solutions:
Ensure the domain (e.g., heyflow-webhook-...run.app) is correct. Even a small typo or incorrect URL will prevent the system from resolving the endpoint.
Check for intermittent internet or DNS issues. DNS acts like a phone book for the internet, it helps your device locate the correct website. If this process is disrupted, the request might fail.
Wait and retry the request after a few minutes.
You can check whether other websites are loading correctly, and try restarting your router if needed in order to fix connection issues.Try using a more reliable or static domain if applicable.
If you are manually constructing the payload, make sure the data is correctly formatted as JSON.
If you are working with a developer, ask them to verify that the data is properly structured. This error can occur if the data is not converted into valid JSON format, which is the standard for sending data.
AxiosError: Request failed with status code 400
Description: Bad Request. Likely due to malformed JSON, missing required fields, or incorrect content-type headers.
Solutions:
Validate the payload: Ensure the data you are sending matches the expected format of the receiving server.
If the payload is not properly structured (for example, not valid JSON), the request may fail. You can use online tools like JSONLint to check and validate the structure of your JSON payload.Confirm all required fields are included and correctly named.
Test the webhook endpoint using webhook.site – This tool allows you to capture and inspect the data being sent by your webhook. It helps verify whether the request is properly formatted before it reaches the destination endpoint.
AxiosError: Request failed with status code 401
Description: Unauthorized request due to missing or invalid authentication.
Solutions:
Check that the authentication details (such as API key, token, or credentials) are properly included in the request headers.
These details are usually provided by the external service you are connecting to. If they are missing or incorrect, the request will be rejected.
AxiosError: Request failed with status code 404
Description: Not Found. The endpoint URL may be incorrect or unavailable.
Solutions:
Make sure you are sending the request to the correct address, using the right resource ID and method (such as GET, POST, etc.). Mistakes in the route, resource reference, or method can prevent the request from reaching the intended destination.
AxiosError: Request failed with status code 409
Description: Conflict. Typically indicates a duplicate or conflicting resource creation.
Solutions:
Check if the resource already exists (e.g., contact or lead).
Check if there is an option to update existing resources instead of creating new ones (upsert). This helps prevent conflicts caused by trying to create duplicate entries.
AxiosError: Request failed with status code 422
Description: Unprocessable Entity. The data format is correct, but semantically invalid (e.g., email format wrong, phone number too short).
Solutions:
Check that the data you are sending follows the expected format. For example, make sure the email address is valid (e.g., [email protected]) or that the phone number has the required length.
Use native input types and validation in Heyflow to ensure correct data entry.
AxiosError: Request failed with status code 500
Description: Internal Server Error. The issue is likely on the receiving server.
Solutions:
Retry the request later.
Contact the API provider with the response ID for deeper investigation.
Error: connect ETIMEDOUT
Description: The request timed out when trying to reach the external service.
Solutions:
Check your internet connection or hosting service.
The external server may be down — try again later.
Consider increasing timeout settings if supported.
AxiosError: Request failed with status code 429
Description: Too many requests were sent in a short period of time. This typically means the destination service is applying rate limiting.
Solutions:
Ensure you are not sending too many requests in a short time frame. Spread out the requests if possible.
Check if the destination service has specific rate limits. If so, wait and retry the request after the recommended cooldown period.