When an n8n workflow fails, the canvas usually shows only a single red message. The useful information is hidden in the execution record: the HTTP status code, the error code returned by the upstream service, and the address the request actually went to. With those three pieces, most errors can be located within minutes.

This article breaks the problem down by error type: 401 and 403 belong to credentials and permissions; 404 is usually the Base URL or model name; 429 is rate limiting and quota; node timeouts and workflow failures depend on configuration and runtime environment; and finally there is JSON parsing failure. At the end, a fixed troubleshooting sequence is provided so a team can turn it into its own runbook.

Note: n8n and OpenAI are trademarks of their respective owners, and this article is not affiliated with those vendors. Model names and prices are subject to the in-site model pricing; node fields depend on the version you are using.

1. Read the execution record first, do not guess

Open Executions in the left sidebar, filter by Failed, and open the failed run. Inspect the input, output, and error details of each node in turn. Record four things: the node name, the HTTP status code, the upstream error code, and the request ID if present. These four determine whether the problem is in the n8n configuration, the network path, or the upstream service.

You can start by roughly sorting common status codes with this table:

Status code Usual meaning Check first
401 Not authenticated or invalid key Whether the credential is selected and the key has expired
403 Authenticated but not permitted Model permissions, IP allowlist
404 Address or model does not exist Base URL path, spelling of the model name
429 Rate limited or quota exhausted Concurrency, retry policy, account quota
400 Invalid request parameters Field names, context length, message format
5xx Temporary upstream failure Retry later; check the service status page

2. 401: a correct key can still fail

A 401 does not always mean "the key is wrong". Other common causes: the credential was created but not selected in the workflow node; copying introduced a space or line break; the test key was disabled; several people share an instance and the node references a different credential; or a self-hosted instance changed N8N_ENCRYPTION_KEY, so the old credential can no longer be decrypted.

The handling order is simple: reselect the credential once, paste the key again, save, and run that node alone. If it still fails, run curl from a machine that can represent the n8n runtime environment:

curl -i https://your-gateway-address/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model-name","messages":[{"role":"user","content":"Reply with OK only"}]}'

If curl succeeds but n8n fails, the problem is in the credential or node configuration. If both fail, the problem is the key, the gateway, or the network. Do not write the key into Code nodes, workflow JSON, or notes fields; those are easy to export and share.

3. 404: Base URL and model name each account for half

In an OpenAI-type credential, the Base URL usually ends at /v1, and the node appends /chat/completions itself. Adding a full path produces addresses like /v1/chat/completions/chat/completions and returns 404. Conversely, the HTTP Request node needs the full URL and cannot take only a domain.

The other half of 404s comes from model names. OpenAI-compatible services often use model_not_found for a nonexistent model; it may arrive as a 404 or wrapped inside a 400. Verify three things: the capitalization of the model name, whether a date suffix is included, and whether the gateway exposes an alias or the upstream original name. The safest approach is to request /v1/models and use only names that appear in the returned list.

A few more details: a trailing slash on the Base URL can produce double slashes; when the gateway sits under a subpath of a reverse proxy, the prefix cannot be omitted; and after switching between test and production, the address may not have been updated.

4. 429: rate limits cannot be handled by retries alone

A 429 means the request was rate limited. There are three common triggers: per-minute request or token limits, concurrency limits, and exhausted account quota or balance. If the response includes a Retry-After value, respect it rather than resending immediately.

In n8n node settings you can enable Retry On Fail, set the maximum attempts to 2 or 3, and configure an increasing wait time. But retries only absorb short-term jitter; they do not solve sustained over-limit conditions. For batch jobs, lower concurrency and process in chunks with Split In Batches or Loop Over Items, leaving an interval between batches. Stagger scheduled jobs where possible, and do not run a debug pass over the full dataset.

5. Node timeouts and workflow failures

Timeouts need to be separated by layer: the HTTP Request node's own timeout, the workflow-level timeout, the reverse proxy or load balancer timeout, and the upstream model generation time. Whichever layer expires first causes the execution to fail, and the wording in the error message usually differs.

Long text generation easily exceeds default limits. You can raise the node timeout moderately while also compressing the input, limiting the maximum output, and splitting the task into smaller pieces. Do not let a workflow wait indefinitely, and do not set the timeout so high that a failure occupies an execution slot for a long time. On self-hosted instances, also check whether the process was restarted and whether workers are online in queue mode.

Node-level failure strategy also needs configuration: for batch jobs, use On Error to continue and retain the failed items; for critical write nodes, choose to stop the workflow. Then configure an Error Workflow that sends the execution ID, node name, and an input summary to a group chat or mailbox. Failure is not what hurts; the absence of records is.

6. JSON parsing failure: the model output is not JSON

A typical error is "JSON parameter needs to be valid JSON", or JSON.parse throwing inside a Code node. The usual reason is that the model added explanatory text or Markdown code fences around the JSON, and field types do not match the agreed schema.

Solve it upstream first: state clearly in the prompt "output JSON only, no code block", and specify fields and types explicitly. If the gateway or model supports structured output, prefer that. Still parse defensively downstream, for example in a Code node:

const raw = $json.text ?? $json.content ?? "";
const cleaned = String(raw)
  .replace(/^```(?:json)?\s*/i, "")
  .replace(/```\s*$/, "")
  .trim();

try {
  return [{ json: JSON.parse(cleaned) }];
} catch (e) {
  return [{ json: { parse_error: true, raw: cleaned } }];
}

When parsing fails, do not silently discard the result. Write the original text to an exception table and sample a few rows manually; this often reveals problems in the prompt or the model's capability.

7. A reusable troubleshooting sequence

  1. Confirm the scope: is a single record failing, or the whole batch or workflow?
  2. Reproduce with curl from the same network environment as n8n to rule out node configuration interference.
  3. Compare the URL, headers, and body that n8n actually sends, focusing on Base URL concatenation.
  4. Request /v1/models to verify the model name, including capitalization and suffix.
  5. Record the status code and error code: 401, 403, and 404 are not worth retrying; 429, 5xx, and timeouts are.
  6. Check timeouts, concurrency, and batch size before adjusting retry parameters.
  7. Write the conclusion into the team runbook with error samples and the fix applied.

FAQ

n8n reports 401, but curl works. Where is the problem?

First check whether the node references the wrong credential, whether the key contains extra spaces or line breaks, and whether the instance's encryption key was changed. You can also add an Authorization header manually in an HTTP Request node for comparison, to confirm whether the issue is credential resolution or request construction.

Does a 404 always mean the Base URL is wrong?

Not necessarily. An extra path in the address, a missing /v1, or a lost reverse-proxy prefix can all produce 404s; a nonexistent model name may also return 404. Confirm the model exists using /v1/models, then check the address level.

How many retries are appropriate for 429?

Usually 2 or 3, with increasing waits and respect for Retry-After. A sustained 429 means concurrency or quota is already exceeded, and more retries only add congestion; reduce batch size or stagger execution instead.

The workflow reports success but the result is empty. How do I investigate?

Open the execution record and inspect each node's output. Confirm whether the model response was overwritten by a downstream field mapping, whether the output was truncated, or whether content filtering was triggered. Then verify that the field names referenced by expressions match the actual structure of the previous step.

What network issues matter for self-hosted n8n?

Make sure the container or host can resolve and reach the gateway domain, and check proxy environment variables, firewall egress rules, and IP allowlists. Scheduled triggers and manual executions may run on different instances, so validate both environments.

Next steps

The general principle for troubleshooting is: gather evidence before changing configuration, and fix addresses and credentials before discussing retries and timeouts. For a unified OpenAI-compatible entry point, separate virtual keys, and usage records, sign up for ZSQH AI Gateway; models and prices are subject to the model pricing page.

Related reading: