n8n request failed with status code 431

What n8n request failed with status code 431 actually means

When an n8n execution stops with "request failed with status code 431", a server has refused the request because of its headers, not its body. 431 is the standard HTTP status for "Request Header Fields Too Large". Either a single header or all the headers together went beyond what the receiving server is willing to read. The request was rejected before the server looked at the payload, so nothing in the body caused it.

Two points matter before you change anything. First, this error is usually deterministic. Sending the same headers again will fail the same way, so blind retries only add noise and delay. Second, the message does not say which component rejected the request. It could be the target API, an API gateway or load balancer in front of it, or a reverse proxy sitting in front of your own n8n instance. Finding that hop is the first real diagnostic step.

Where oversized headers usually come from

Start by working out the direction of the failing call. If an HTTP Request node or an app node calls an external service, the limit belongs to that service and you can only change what you send. If something is calling your n8n webhook or editor through a proxy, the limit lives in infrastructure your team controls. The fix and the people involved differ between the two cases.

In outbound calls, the usual causes come from how headers are built rather than from the platform itself:

• An expression that maps a whole item, array or long text field into a header value instead of the body
• Bearer tokens or JWTs that carry many claims, scopes or group memberships
• Cookies that build up across calls and are forwarded on every request
• Headers from an incoming webhook copied wholesale into an outgoing request
• Headers appended inside a loop so they repeat or grow on each iteration

Diagnosing the failing request step by step

Open the failed execution and inspect the node that raised the error. Look at its input item and at every header it was configured to send, with expressions resolved against that specific item. Header size often depends on the data, which explains why a workflow can succeed for most records and fail on a few.

Then confirm which hop answered. Check whether the response came from the service you meant to reach or from an intermediary. Response headers, the error page format, or proxy logs on your side usually make this clear. Use a short checklist so the investigation stays focused:

• Which node failed, and is the call outbound or inbound?
• Which header is unusually long once expressions are resolved?
• Does the failure follow particular records, accounts or tokens?
• Did a credential, scope list or upstream integration change recently?
• Is the rejecting component one your team owns or one you have to work around?

Worked example: a hypothetical CRM sync that fails on some records

Example (hypothetical, for illustration only): a team runs an n8n workflow that reads contacts from a CRM and pushes them to an internal API. To pass context, someone added a custom header whose value is an expression returning the contact's notes. Most contacts have short notes and sync without trouble. A handful of long-standing accounts have notes thousands of characters long, and those executions fail with status code 431.

Inspecting the failed executions shows that every failure involves a contact with very long notes, and that the gateway in front of the internal API returned the response. The cause is now clear. The header is carrying data that belongs in the request body, and the gateway is enforcing its limit as designed.

The controlled fix is to move the notes into the JSON body, keep the header as a short identifier, and rerun only the affected items. Two shortcuts should be avoided: dropping the authorization header to make the request fit, and asking for gateway limits to be raised without understanding why headers grew. Neither one removes the underlying design problem.

Detecting and recovering with n8n error handling

The n8n documentation on error handling describes error workflows. You build a separate workflow that starts with an Error Trigger node and select it in a workflow's settings. When an execution fails, the error workflow receives details such as the workflow, the failing node and the error message. You can route those details to the people who own the integration. The same documentation covers the Stop And Error node, which lets you fail on purpose. For example, you can stop when a computed header value exceeds a length you consider safe, before the request is ever sent.

Good alerts for this error carry actionable context: the workflow name, the node, the status code, and the record or credential involved. With that context, whoever responds can see quickly whether a data change or a configuration change triggered the failure. Recovery should stay controlled. Correct the header construction, then reprocess the specific failed items rather than replaying everything. No workaround should loosen authentication, skip access controls or move personal data somewhere less protected.

Datvero is built to watch n8n workflows and turn failures like this into alerts with diagnostic context and tracked incidents. That only covers the detection and follow-up side. Header limits, credentials and proxies stay governed by each team's own platform configuration and operating process.

Preventing a repeat after the incident

Once the workflow is healthy again, spend a few minutes on post-incident improvement. Write down which component enforces header limits for each critical integration, and who can change them. Add guards that check header length before sending wherever headers are built from variable data. Make it a team convention that bulk content goes in request bodies, never in headers.

If large tokens were the cause, review the scopes and claims with the owner of the identity provider instead of trimming tokens in the workflow. Then track whether the error comes back. A single recurrence after a credential rotation or upstream change tells you more than any amount of speculation about limits.