n8n HTTP Request Node: The Auth and Error Playbook

The n8n HTTP Request node is the node that calls an external API. It is the most-used node in any real workflow, the one that connects n8n to the rest of the internet, and the one that breaks the most often. That is the short version. The longer version is that the HTTP Request node is powerful, configurable, and surprisingly unforgiving in the places most tutorials skip: authentication, error handling, and pagination.

Every n8n workflow that does real work ends up with at least one HTTP Request node. Most of them end up with a dozen. The node handles the usual suspects (GET, POST, PUT, PATCH, DELETE), the usual auth (Bearer, Basic, OAuth2, API Key, Header Auth), the usual formats (JSON, form data, multipart, raw), and the usual gotchas (rate limits, pagination, retries, timeouts). The gotchas are where most workflows fail in production.

This post is a working engineer’s take on the HTTP Request node: the right way to configure it, the auth patterns that bite, the error handling that survives production, and the deployment story that keeps the workflow running. It assumes you already know what n8n is, that you have at least one workflow that calls an external API, and that you have hit at least one of the auth or error messages that are not in the official docs.

Table of contents

• The short version
• What the HTTP Request node actually does
• The five authentication patterns that matter
• The auth footguns the docs skip
• Error handling that survives production
• Pagination, the silent workflow killer
• Rate limits and the polite-request pattern
• The credential-isolation pattern for production
• Self-hosting n8n: what changes
• FAQ

The short version

The HTTP Request node is a thin wrapper around an HTTP client. It exposes the request method, URL, headers, body, authentication, and response handling. The defaults are sensible for ad hoc calls. For production workflows, every default needs to be reviewed.

The most common production failures are authentication misconfiguration, missing error handling, and ignored rate limits. All three are fixable. None of them are fixed by the default settings.

The right pattern is: configure authentication once via n8n’s credential store, set explicit error handling on every node, add pagination only when the API actually paginates, and add a retry policy that respects the API’s rate limit headers. Then test the workflow end to end with a real failure case.

What the HTTP Request node actually does

The HTTP Request node sends a single HTTP request and returns the response. The configuration has six load-bearing fields and a few dozen optional ones.

Method. GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. The method is a dropdown, not free text. n8n sets sensible defaults for each method (GET has no body, POST defaults to JSON).

URL. The full URL of the endpoint. n8n supports expressions in the URL, so {{$json.userId}} is interpreted against the incoming item. This is how you parameterize the request.

Authentication. The dropdown has Generic Auth Type, which exposes a sub-menu of credential types: None, Basic Auth, Digest Auth, Header Auth, OAuth1, OAuth2, Query Auth, and Custom. The choice matters more than the docs suggest.

Headers. A list of name: value pairs. n8n supports expressions in the value, so you can set a header from the incoming data.

Body. The request body. The form changes based on the content type: JSON, Form Data, Form URL-Encoded, Multipart Form Data, Binary, or Raw. The default is JSON. The body field supports expressions.

Options. A long list: timeout, redirect following, response format, batching, proxy, SSL verification, pagination. The defaults are fine for ad hoc calls. For production, every one of these is a decision.

The shape is honest. The node is a thin wrapper. The power is in the configuration. The traps are in the configuration.

The five authentication patterns that matter

Most production workflows end up using the same five authentication patterns. The order is roughly the popularity among real APIs.

Bearer token (most common). The API expects an Authorization: Bearer <token> header. In n8n, this is the “Header Auth” credential type with the header name Authorization and the value Bearer <token>. The token is stored in the credential, not in the workflow. The workflow references the credential by name. The token is rotated by editing the credential, not the workflow.

{
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "httpHeaderAuth": {
    "name": "Authorization",
    "value": "Bearer {{$credentials.apiToken}}"
  }
}

This is the right default for any modern API. If the API supports Bearer, use Bearer.

Basic Auth. The API expects Authorization: Basic <base64(username:password)>. In n8n, this is the “Basic Auth” credential type. The credential stores the username and password. The workflow references the credential.

Basic Auth is showing its age. Most modern APIs use Bearer or API Key. If the API you are integrating still uses Basic, the API itself is probably also using an old security model. Treat the integration with appropriate caution.

API Key in query string. The API expects ?api_key=<key> on every request. In n8n, this is the “Query Auth” credential type. The credential stores the key name and value. The workflow references the credential.

API keys in query strings are visible in server logs, browser history, and any HTTP debugging tool. If the API offers the key in a header instead, use the header. If the API only offers the query string, use it but do not log the URL with the key in production.

API Key in header. The API expects X-API-Key: <key> (or similar) on every request. In n8n, this is the “Header Auth” credential type, like Bearer but with a different header name.

This is the cleanest pattern for any API that uses a static key. The key is rotated by editing the credential.

OAuth2. The API uses an OAuth2 flow: redirect the user to the provider, the user authorizes, the provider returns an authorization code, the workflow exchanges the code for an access token and a refresh token. n8n’s OAuth2 credential type handles the dance, stores the tokens, and refreshes the access token when it expires.

OAuth2 is the right answer for any API that supports it. The pattern is more setup than a static key, but the workflow never has to know the access token. The credential handles the refresh.

The auth footguns the docs skip

The official n8n docs cover the happy path. The community forums and GitHub issues cover the cases that bite in production.

OAuth1 is not the same as OAuth2. Some older APIs (Twitter v1, certain medical and EMR systems) use OAuth1. n8n has a credential type for OAuth1, but the dance is different from OAuth2. The workflow that worked with OAuth2 will not work with OAuth1, and the error message is “Unauthorized” with no hint that the auth type is the problem. The fix is to read the API docs carefully and pick the right credential type.

Header Auth is not just for Authorization. The “Header Auth” credential type can set any header. If the API expects X-API-Key or X-Auth-Token or a custom header, Header Auth is the right credential type. The error message for a wrong header name is “401 Unauthorized,” which is misleading. The fix is to check the exact header name the API expects.

The credential is per-workflow in a way that surprises people. A credential created in one workflow is available to other workflows in the same n8n instance, but the credential is not shared across instances. If you self-host n8n on your laptop and on a production platform, the credentials are separate. The fix is to set up the credential on each instance, or to use an external secret store (HashiCorp Vault, AWS Secrets Manager) and read the secret at workflow startup.

The API expects a header that n8n does not expose. Some APIs require a custom header (a nonce, a signature, a timestamp) that is not in the standard list. The fix is to add the header in the “Headers” section of the node, not in the credential. The credential handles auth. The headers section handles everything else.

The token is short-lived and the refresh is not automatic. Some APIs issue access tokens that expire in 5 minutes. The refresh dance is supported, but the workflow has to be configured for it. The error message for an expired token is “401 Unauthorized,” which can look like an auth misconfiguration. The fix is to check the API’s token lifetime and configure the refresh.

The credential is rotated, but the workflow still has the old value. n8n caches credentials in memory. When the credential is updated, the workflow that references it may need a restart to pick up the new value. The fix is to restart the workflow after rotating a credential, or to use a credential type that supports hot-reload.

Error handling that survives production

The HTTP Request node has a default error handling that stops the workflow on any non-2xx response. This is the wrong default for production. The right default depends on what the workflow is doing.

For a workflow that processes one item at a time: the default is fine. If the request fails, the workflow stops, the error is logged, and the user is notified. The next run retries the failed item.

For a workflow that processes a batch of items: the default is wrong. If one item’s request fails, the entire batch stops. The right setting is “Continue on Fail,” which lets the rest of the batch complete and reports the failed items in a separate branch.

For a workflow that needs to retry on transient errors: the right setting is a retry policy. The HTTP Request node has a “Retry on Fail” option that retries the request up to N times with an exponential backoff. The right pattern is to retry on 429 (rate limit) and 5xx (server error), and to fail immediately on 4xx (client error) other than 429.

For a workflow that needs to alert on error: the right pattern is a separate error branch. The HTTP Request node supports an “On Error” output that runs only when the request fails. The error branch can send a notification, log to a central system, or write to a dead-letter queue.

The honest summary: every HTTP Request node in a production workflow needs an explicit decision about what happens on failure. The default is the wrong answer for almost every real use case.

Pagination, the silent workflow killer

Most APIs that return a list of items paginate the response. The HTTP Request node has a pagination option, but the option is off by default. The workflow that worked with 10 items in development can fail silently with 10,000 items in production because the pagination was never configured.

Offset-based pagination. The API returns a list and a next_offset field. The HTTP Request node’s pagination option supports this directly. Set the “Pagination Mode” to “Update a Parameter in the URL or Body,” and configure the parameter to increment with each page.

Cursor-based pagination. The API returns a list and a next_cursor field. The cursor is opaque. The HTTP Request node supports this with the same pagination option, but the configuration is “Update a Parameter with the Response Value.” The node reads next_cursor from the response and uses it in the next request.

Link header pagination. The API returns the next page in a Link header (the GitHub pattern). The HTTP Request node supports this with the “Link Header” pagination mode. The node parses the rel="next" link and uses it in the next request.

Page-number pagination. The API uses ?page=1, ?page=2, etc. The HTTP Request node supports this with the “Update a Parameter” mode, incrementing the page number on each iteration.

The trap is the workflow that works for one page. If the API has 100 pages and the workflow only requests one, the workflow is silently missing 99% of the data. The fix is to always configure pagination when the API paginates, and to test the workflow with a dataset that requires more than one page.

Rate limits and the polite-request pattern

Every real API has a rate limit. The HTTP Request node has a retry option, but the retry option does not read the rate limit headers. The workflow that retries blindly can be the workflow that gets the API key revoked.

The pattern that works. Read the X-RateLimit-Remaining and X-RateLimit-Reset headers (or the API’s equivalent). When X-RateLimit-Remaining drops below a threshold, pause the workflow. When the X-RateLimit-Reset time arrives, resume.

In n8n, the pattern is a small workflow:

1. HTTP Request node calls the API.
2. A Function or Set node reads the rate limit headers.
3. An IF node branches: if remaining is below threshold, wait. Otherwise, continue.
4. A Wait node pauses for the reset time.

The pattern is more setup than a blind retry, but it is the difference between a workflow that the API tolerates and a workflow that gets the key revoked.

The “polite request” pattern. Add a small delay between requests. Even 100 ms is enough to keep a single API key from hitting the rate limit on a moderate workload. The HTTP Request node has a “Wait” option that can be set per request.

The error-response pattern. When the API returns 429 (Too Many Requests), the response usually includes a Retry-After header. The HTTP Request node’s retry option can be configured to read this header and wait the right amount of time. The pattern is “retry on 429, wait per Retry-After, then retry again.”

The credential-isolation pattern for production

The most common production failure with the HTTP Request node is a leaked credential. The fix is the credential-isolation pattern.

Step 1: the credential lives in n8n’s credential store, not in the workflow. The workflow references the credential by name. The credential stores the API key, the OAuth tokens, or the username and password. The workflow never has the raw value.

Step 2: the credential store is encrypted at rest. n8n’s credential store is encrypted by default. The encryption key is set via the N8N_ENCRYPTION_KEY environment variable. The key is the secret, not the credentials. The key belongs in a secret manager (HashiCorp Vault, AWS Secrets Manager, a PaaS’s environment variables).

Step 3: the credential is scoped to the least privilege the API offers. If the API supports a read-only token, use the read-only token. If the API supports a sandbox credential, use the sandbox credential for development and the production credential for the production workflow.

Step 4: the credential is rotated on a schedule. Most APIs support token rotation. The credential is updated, the workflow is restarted, the new credential is in use. The schedule depends on the API, but a quarterly rotation is a reasonable default for static keys. OAuth tokens rotate automatically.

Step 5: the credential is audited. n8n logs the workflows that use each credential. The audit log is the answer to “who has access to this API and when did they last use it.” The log is not a substitute for the API provider’s audit, but it is a useful complement.

The pattern is the same hygiene as any secret in a production system. The HTTP Request node is the consumer. The credential store is the source of truth. The secret manager is the backing store.

Self-hosting n8n: what changes

n8n is open source and self-hostable. The self-hosted version is the same code as the cloud version, with a few additional responsibilities.

The n8n instance runs as a service. A Docker container, a Kubernetes pod, a PaaS service. The instance has a health check, a deploy story, and the same uptime requirements as any other production service.

The credential store is on the same host or in an external secret manager. The default is local. For production, the external secret manager is the better answer, because the secret manager survives a host failure and supports audit.

The database is on a persistent layer. n8n stores workflow definitions, execution history, and credentials in a Postgres database. The database is durable; the n8n instance is replaceable. The pattern is the same as any other stateful service: data on a managed database, instances behind a load balancer.

The execution history grows. n8n keeps the last N executions of each workflow. The execution history is in the database. The retention is configurable. For production, set a retention that matches the audit requirements and the storage budget.

The webhooks the workflows expose are reachable. If the workflow exposes a webhook (the n8n “Webhook” node, often paired with the HTTP Request node), the webhook URL is on the public internet. The URL is protected by a shared secret, but the URL is public. The hosting platform needs to expose the port and the path. The RunxBuild services platform handles this; a self-hosted n8n on a VPS needs a reverse proxy and a TLS certificate.

The cost is the database, the host, and the secret manager. A self-hosted n8n is not free in production. The cost is the database (Postgres on a managed service), the host (a small container is enough for moderate workloads), and the secret manager (optional, but recommended for production). The cost is usually lower than the cloud version of n8n, but it is not zero.

For teams that want n8n without the self-hosting overhead, the RunxBuild services platform is a clean fit: the n8n service is a container, the database is a managed Postgres, the secret manager is the platform’s environment variables, and the observability is the platform’s log and metric stream. The cost is in the calculator.

FAQ

What is the n8n HTTP Request node?

The n8n HTTP Request node is a node that sends a single HTTP request and returns the response. It supports the standard HTTP methods, authentication types, request formats, and response handling. It is the most-used node in any n8n workflow that integrates with an external API.

What authentication types does the HTTP Request node support?

None, Basic Auth, Digest Auth, Header Auth, OAuth1, OAuth2, Query Auth, and Custom. Bearer tokens use the Header Auth credential type with the header name Authorization and the value Bearer <token>. API keys in headers use the same type with a different header name.

How do I handle pagination in the HTTP Request node?

The node has a pagination option that supports offset-based, cursor-based, page-number, and Link header pagination. The option is off by default. The workflow that does not configure pagination will only fetch the first page of results, which is the most common silent failure in production workflows.

How do I handle rate limits in the HTTP Request node?

The right pattern is to read the API’s rate limit headers (X-RateLimit-Remaining and X-RateLimit-Reset), pause when the remaining is low, and respect the Retry-After header on 429 responses. The HTTP Request node’s retry option can be configured to wait the right amount of time before retrying.

How do I store credentials in n8n?

Credentials are stored in n8n’s credential store, which is encrypted at rest. The encryption key is set via the N8N_ENCRYPTION_KEY environment variable. The key is the secret, not the credentials. The key belongs in a secret manager (HashiCorp Vault, AWS Secrets Manager, a PaaS’s environment variables).

Can the HTTP Request node call a private API?

Yes. If the API is on a private network that the n8n instance can reach, the HTTP Request node can call it. The pattern is the same as a public API, but the URL is the private URL and the network path is configured at the platform level (a private network, a VPC peering, or a service mesh).

What is the difference between OAuth1 and OAuth2 in the HTTP Request node?

OAuth1 is the older protocol used by some legacy APIs (Twitter v1, certain EMR systems). OAuth2 is the modern protocol used by most current APIs. The credential types in n8n are separate. A workflow configured for OAuth2 will not work with OAuth1, and the error message is “Unauthorized” with no hint that the auth type is the problem.

Can I rotate a credential without restarting the workflow?

It depends on the credential type. Static keys (Bearer, API Key) are cached in memory and may require a workflow restart. OAuth tokens refresh automatically. The right pattern is to plan a workflow restart as part of the rotation process, or to use an external secret manager that the workflow reads at startup.

How do I deploy a self-hosted n8n for production?

Run n8n as a container on a PaaS or Kubernetes cluster, with the database on a managed Postgres, the credentials in a secret manager, the webhooks behind a reverse proxy with TLS, and the execution history retention set to match the audit requirements. The RunxBuild services platform is a clean fit for this stack.

Can the HTTP Request node handle binary files?

Yes. The request body can be set to Binary, and the response can be set to File. The pattern is to download a file (PDF, image, CSV) from one API, store it in the workflow’s binary data, and upload it to another API. The binary data is held in memory for the duration of the workflow execution. For large files, the workflow should stream the data rather than holding it in memory.