HTTP Request node에서 자주 발생하는 오류와 문제, 그리고 이를 해결하거나 문제를 해결하기 위한 단계를 소개합니다.

Bad request - 매개변수를 확인하세요#

이 오류는 노드가 잘못된 요청을 나타내는 400 오류를 수신할 때 표시됩니다. 이 오류는 대부분 다음과 같은 이유로 발생합니다.

• Query Parameter에서 잘못된 이름이나 값을 사용하고 있는 경우입니다.
• Query Parameter에 배열 값을 전달하고 있지만 배열 형식이 올바르지 않은 경우입니다. Array Format in Query Parameters 옵션을 사용해 보세요.

쿼리 매개변수 형식을 지정하려면 사용 중인 서비스의 API 문서를 검토하세요.

요청한 리소스를 찾을 수 없음#

이 오류는 입력한 엔드포인트 URL이 유효하지 않을 때 표시됩니다.

이는 URL의 오타나 더 이상 사용되지 않는(deprecated) API 때문일 수 있습니다. 유효한 엔드포인트인지 확인하려면 사용 중인 서비스의 API 문서를 참조하세요.

Connection refused (ECONNREFUSED)#

이 오류는 노드가 네트워크상의 호스트에 도달했지만 대상 포트에 리스너가 없을 때 표시됩니다. TCP 연결이 능동적으로 거부되는 것으로, DNS 실패나 타임아웃, 방화벽 차단이 아닙니다.

셀프 호스팅 n8n에서 가장 흔한 원인은 Docker 네트워킹입니다. n8n 컨테이너 내부에서 localhost와 127.0.0.1은 호스트 머신이 아니라 컨테이너 자기 자신을 가리킵니다. 노드에서 http://localhost:5000으로 보내는 요청은 n8n 컨테이너의 5000번 포트로 전달되며, 그곳에는 아무것도 리스닝하고 있지 않습니다.

이를 해결하려면 컨테이너가 라우팅할 수 있는 이름으로 대상 주소를 지정하세요.

• 호스트 머신의 대상, Docker Desktop(Mac 또는 Windows): URL 필드에 http://host.docker.internal:<port>를 사용하세요. Docker Desktop이 이 호스트 이름을 자동으로 추가합니다.
• 호스트 머신의 대상, Linux: 컨테이너에 --add-host=host.docker.internal:host-gateway를 전달하거나, docker-compose.yml에서 extra_hosts를 설정하세요.

  services:
    n8n:
      image: n8nio/n8n
      extra_hosts:
        - "host.docker.internal:host-gateway"
  

  동일한 해결 방법이 MySQL node 문서에도 설명되어 있습니다.
• 동일한 Compose 스택 내 다른 컨테이너의 대상: 서비스 이름을 호스트 이름으로 사용하세요. 예를 들어 http://my-api:5000과 같습니다. 게시된 ports: 매핑이 아니라 컨테이너의 내부 포트를 참조하세요.

Docker 밖에서도 Node.js 17 이상에서 발생하는 별개의 원인이 있습니다. localhost가 127.0.0.1보다 먼저 IPv6 주소 ::1로 해석되는 것입니다. 대상이 127.0.0.1에만 바인딩되어 있으면 IPv6 시도가 거부되고, HTTP Request node 내부에서 IPv4로의 폴백이 항상 성공하는 것은 아닙니다.

URL 필드에서 localhost 대신 http://127.0.0.1:<port>를 사용하세요.

워크플로를 다시 실행하기 전에 수정 사항을 확인하려면, n8n 컨테이너에 exec로 접속하여 wget으로 URL을 시도해 보세요.

docker exec -it n8n wget -qO- http://host.docker.internal:5000/health

컨테이너 내부에서 wget이 성공하면 HTTP Request node도 성공합니다. wget 역시 "connection refused"를 반환한다면, 원인은 n8n이 아니라 네트워크나 대상 서비스에 있습니다.

n8n Cloud에서는 워크플로가 n8n의 인프라에서 실행됩니다. localhost가 존재하지 않으며 사용자의 머신에 있는 서비스로 접근할 경로도 없습니다. 로컬 전용 대상을 터널을 통해 노출하고 HTTP Request node에서 공개 URL을 사용하세요.

JSON 매개변수는 유효한 JSON이어야 합니다#

이 오류는 매개변수를 JSON으로 전달했지만 유효한 JSON 형식이 아닐 때 표시됩니다.

이를 해결하려면 입력한 JSON에서 다음 문제가 없는지 검토하세요.

• JSON 검사기나 구문 파서에서 JSON을 테스트하여 따옴표 누락, 쉼표 과다 또는 누락, 잘못된 형식의 배열, 대괄호나 중괄호 과다 또는 누락 등의 오류를 찾으세요.
• 노드에서 Expression을 사용했다면, 전체 JSON을 이중 중괄호로 감쌌는지 확인하세요. 예를 들면 다음과 같습니다.

  {{
      {
      "myjson":
      {
          "name1": "value1",
          "name2": "value2",
          "array1":
              ["value1","value2"]
      }
      }
  }}
  

Forbidden - 자격 증명을 확인하세요#

이 오류는 노드가 인증 실패를 나타내는 403 오류를 수신할 때 표시됩니다.

이를 해결하려면 선택한 자격 증명을 검토하고 해당 자격 증명으로 인증할 수 있는지 확인하세요. 다음이 필요할 수 있습니다.

• 선택한 작업을 수행할 수 있도록 API 키나 계정의 권한 또는 범위를 업데이트합니다.
• 제네릭 자격 증명의 형식을 다르게 지정합니다.
• 적절한 권한이나 범위를 가진 새 API 키나 토큰을 생성합니다.

429 - 서비스가 사용자로부터 너무 많은 요청을 받고 있습니다#

이 오류는 노드가 호출 중인 서비스로부터 429 오류를 수신할 때 표시됩니다. 이는 대부분 해당 서비스의 속도 제한(rate limit)에 도달했음을 의미합니다. 자세한 내용은 Handling API rate limits 페이지에서 확인할 수 있습니다.

이 오류를 해결하려면 HTTP request node의 내장 옵션 중 하나를 사용할 수 있습니다.

배칭#

이 옵션을 사용하면 요청을 배치로 전송하고 요청 사이에 지연을 도입할 수 있습니다.

1. HTTP Request node에서 Add Option > Batching을 선택합니다.
2. 각 요청에 포함할 입력 항목 수를 Items per Batch에 설정합니다.
3. 요청 사이에 지연(밀리초 단위)을 도입하려면 **Batch Interval (ms)**를 설정합니다. 예를 들어 초당 하나의 요청을 API에 보내려면 **Batch Interval (ms)**를 1000으로 설정합니다.

실패 시 재시도#

이 옵션을 사용하면 시도가 실패한 후 노드를 재시도할 수 있습니다.

1. HTTP Request node에서 Settings로 이동하여 Retry on Fail을 활성화합니다.
2. n8n이 노드를 재시도할 최대 횟수를 Max Tries에 설정합니다.
3. 재시도 사이에 원하는 지연 시간(밀리초 단위)을 **Wait Between Tries (ms)**에 설정합니다. 예를 들어 요청을 다시 시도하기 전 1초를 기다리려면 **Wait Between Tries (ms)**를 1000으로 설정합니다.

업로드한 파일의 파일 이름이 잘못 전달됨#

Body Content Type을 Form-Data로 설정하고 파일을 보내면, n8n은 multipart/form-data 파트의 파일 이름을 Name 필드가 아니라 바이너리 데이터에서 가져옵니다. Name은 폼 필드 이름만 설정합니다. 바이너리 데이터에 파일 이름이 없으면 n8n은 file을 보냅니다.

수신하는 API가 폼 필드 이름이 아니라 파일 이름으로 업로드를 식별하거나, 특정 이름 또는 확장자를 요구하는 경우에 영향을 줍니다. 요청은 도착하지만 API가 이를 거부하며, 파일이 없다는 400 오류가 자주 발생합니다. 예를 들어 Convert to File node의 Convert to Text File 작업은 출력 이름을 기본값 file.txt로 지정하므로, index.html을 기대하는 API는 파일을 찾지 못합니다.

해결하려면 HTTP Request node 앞에서 바이너리 데이터에 파일 이름을 설정하세요.

• Convert to File node에서 File Name 옵션을 API가 기대하는 이름으로 설정합니다.
• Code node에서 바이너리 속성에 파일 이름을 설정합니다.

for (const item of $input.all()) {
	item.binary.data.fileName = 'index.html';
}
return $input.all();

n8n은 바이너리 데이터에 저장된 MIME 타입을 파트의 Content-Type으로 복사하므로, API가 이를 확인한다면 MIME 타입도 함께 설정하세요.

파일을 보낼 때 Unsupported media type (415) 발생#

이 오류는 API가 multipart/form-data를 기대하지만 요청 본문이 multipart가 아닐 때 표시됩니다.

Body Content Type > n8n Binary File은 파일을 요청 본문 전체로 보냅니다. n8n은 Content-Type을 바이너리 데이터에 저장된 MIME 타입으로 설정하며, 없으면 application/octet-stream으로 설정합니다. multipart 봉투나 경계(boundary)는 추가하지 않습니다. multipart 업로드만 허용하는 API는 이 요청을 거부합니다.

같은 파일을 multipart 업로드로 보내려면 다음과 같이 합니다.

1. Body Content Type을 Form-Data로 설정합니다.
2. Body Parameters 항목을 추가하고 Type을 n8n Binary File로 설정합니다.
3. Name을 API 문서에 나온 폼 필드 이름으로 설정합니다.
4. Input Data Field Name을 파일이 들어 있는 바이너리 속성(예: data)으로 설정합니다.