HTTP Request node 자주 발생하는 문제

요약

HTTP Request node에서 자주 발생하는 오류와 문제, 그리고 이를 해결하거나 문제를 해결하기 위한 단계를 소개합니다. 이 오류는 노드가 잘못된 요청을 나타내는 400 오류를 수신할 때 표시됩니다. 쿼리 매개변수 형식을 지정하려면 사용 중인 서비스의 API 문서를 검토하세요.

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: docker.n8n.io/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의 내장 옵션 중 하나를 사용할 수 있습니다.

배칭#

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

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

실패 시 재시도#

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

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