n8n API 호출 실패 시 확인할 7가지 점검법

n8n에서 외부 API를 붙이다 보면 한 번쯤은 HTTP Request 노드가 빨갛게 멈추는 순간을 만나게 된다. 문제는 실패 자체보다 그 다음이다. 401인지 404인지, 아니면 응답이 느려서 끊긴 건지에 따라 봐야 할 곳이 완전히 다른데, 처음에는 에러 문구만 보고 어디서부터 손대야 할지 감이 잘 오지 않는다. 특히 워크플로우 안에서 API 호출이 중간 허리 역할을 하고 있다면, 한 번의 실패가 뒤쪽 자동화 전체를 멈추게 만든다.

실무에서는 API 호출 실패를 “노드 하나가 안 됐다” 수준으로 보지 않는 편이 낫다. 대부분은 URL 경로, 인증, 메서드, 헤더, 응답 포맷, SSL, Rate Limit, 타임아웃처럼 비교적 정해진 범주 안에서 원인이 나온다. 즉, 모든 경우를 새로 추리할 필요는 없고, 오류 코드를 기준으로 범위를 빠르게 줄이는 습관이 중요하다.

이 글은 단순히 오류 뜻만 모아놓은 설명이 아니라, n8n HTTP Request 노드가 실패했을 때 시간을 덜 버리기 위해 어디부터 확인해야 하는지 정리한 점검 가이드다. 테스트에서는 잘 됐는데 운영에서만 실패하는 경우, Postman에서는 되는데 n8n에서만 안 되는 경우, 응답은 200인데 다음 노드에서 멈추는 경우까지 포함해서 실무형으로 풀어보겠다.

오류 코드를 먼저 나누면 점검 범위가 크게 줄어든다

API 호출이 실패했을 때 가장 흔한 실수는 모든 설정을 한꺼번에 뒤지는 것이다. URL도 보고, 인증도 보고, Body도 보고, 상대 서비스 상태 페이지도 보고, SSL도 만지다가 시간이 길어진다. 그런데 실제로는 응답 코드만 나눠도 점검 방향이 꽤 선명해진다.

400번대는 대체로 내가 보낸 요청 형식에 문제가 있는 경우다. URL 경로가 틀렸거나, 인증이 빠졌거나, 필수 파라미터가 누락됐거나, 메서드가 맞지 않거나, Content-Type이 어긋난 경우가 여기에 들어간다. 반대로 500번대는 상대 서버 쪽 문제인 경우가 많다. 이때는 n8n 설정을 너무 오래 붙들고 있어도 해결이 안 될 수 있다.

에러 코드 없이 ECONNREFUSED, ENOTFOUND, ETIMEDOUT 같은 시스템 에러가 보이면 네트워크 계층부터 봐야 한다. 이런 경우는 노드 설정을 바꾸는 것보다 DNS, 대상 서버 포트, 프록시, 방화벽, SSL 같은 바깥 환경이 먼저 원인인 경우가 많다.

n8n API 호출 실패 원인 점검을 위한 HTTP Request 노드 설정 화면

1. URL 오타와 경로 문제는 기본이지만 가장 자주 터진다

404 Not Found는 너무 단순해 보여서 오히려 늦게 발견하는 경우가 많다. API 버전이 URL 안에 들어가는 서비스라면 /v1/, /v2/ 차이만으로도 바로 404가 난다. 끝 슬래시 하나, 리소스 경로 하나만 달라도 결과는 동일하다.

n8n에서 특히 까다로운 건 URL 필드에 Expression을 쓸 때다. 표면상으로는 정상처럼 보이는데, 실제 실행 시점에는 변수 값이 비어 있어서 https://api.example.com/users/undefined 같은 주소가 만들어질 수 있다. 이때는 URL 입력칸만 보는 게 아니라, 실행 결과의 Request 내용을 보고 실제 어떤 URL이 전송됐는지를 확인해야 한다.

또 하나 자주 놓치는 것이 API 문서 변경이다. 외부 서비스가 엔드포인트를 바꾸거나 버전을 올렸는데, 예전 예제 코드를 그대로 써서 실패하는 경우가 있다. 이때는 n8n 문제가 아니라 API 문서와 코드 예제가 더 오래된 상태일 수 있다.

2. 401은 거의 항상 인증 문제지만, 값보다 위치에서 더 많이 틀린다

401 Unauthorized가 뜨면 많은 사람이 “API Key가 틀렸나?”부터 생각한다. 물론 그럴 수도 있지만, 실제로는 값 자체보다 어디에 넣었는지가 더 자주 문제다. 어떤 API는 Authorization: Bearer {token}를 요구하고, 어떤 API는 X-API-Key 헤더를 쓰며, 어떤 서비스는 Query Parameter에 api_key를 붙여야 한다. 이름과 위치가 문서와 정확히 일치하지 않으면 값이 맞아도 바로 401이 난다.

n8n에서는 기본 Credential로 처리할 수도 있고, 헤더를 직접 넣을 수도 있다. 이때 Bearer 뒤 공백을 빼먹거나, 헤더 이름 철자를 바꾸거나, 복사한 키 앞뒤에 보이지 않는 공백 문자가 들어가서 실패하는 경우가 생각보다 흔하다. 테스트 단계에서는 그냥 지나가는데 운영 배포 후에만 재현되는 이유도 이런 사소한 입력 차이인 경우가 많다.

OAuth2를 쓴다면 토큰 만료도 봐야 한다. 테스트 때는 잘 되는데 며칠 뒤 자동 실행에서만 실패한다면, 액세스 토큰이나 리프레시 토큰 정책이 원인일 가능성이 높다. 이건 특히 구글 계열이나 권한 범위(scope)에 민감한 API에서 자주 만난다.

인증 방식주요 입력 위치자주 틀리는 부분
Bearer TokenAuthorization 헤더Bearer 접두어/공백 누락, 공백 문자 포함
API KeyHeader 또는 Query파라미터 이름 불일치, 위치 혼동
OAuth2Credential 연동토큰 만료, 권한 범위 부족
Basic AuthAuthentication 설정아이디/비밀번호 인코딩, 특수문자 처리

인증 정보 자체를 어떻게 관리할지 감이 덜 잡힌다면 [관련 글: n8n 보안 완벽 가이드 자격 증명과 웹훅을 안전하게 관리하는 법 더 알아보기]를 같이 보면 도움이 된다.

3. 메서드가 다르면 요청은 도착해도 의미가 없다

GET, POST, PUT, PATCH, DELETE는 이름만 다른 옵션이 아니라 서버가 아예 다르게 해석하는 요청이다. 문서에는 POST라고 적혀 있는데 n8n 노드 기본값이 GET으로 되어 있는 상태로 그냥 실행하면 405 Method Not Allowed가 뜰 수 있다. 그런데 처음 보는 사람은 이 코드를 보자마자 권한 문제나 URL 문제로 오해하기 쉽다.

특히 업데이트 계열 API에서는 PUT과 PATCH를 혼동하기 쉽다. 둘 다 수정처럼 보이지만 서버 구현에 따라 하나만 지원하는 경우가 많다. 그래서 메서드는 “대충 맞겠지”가 아니라 문서 그대로 맞추는 편이 낫다.

4. Content-Type과 Body 포맷이 어긋나면 400에서 오래 막힌다

400 Bad Request는 매우 넓은 범위의 실패를 뜻한다. 그중에서도 자주 나오는 건 Body 포맷 불일치다. n8n에서 JSON으로 보낸다고 생각했는데 실제 API는 application/x-www-form-urlencoded를 기대하거나, 반대로 form-data를 보냈는데 서버는 순수 JSON만 받는 식이다.

여기서 중요한 건 노드 화면에서 어떻게 보이느냐보다 실제 전송된 요청이다. Body 입력칸을 채워놨더라도 Send Body가 꺼져 있으면 요청에는 포함되지 않는다. Content-Type을 JSON으로 놔두고 문자열을 직접 넣는 식도 종종 문제를 만든다. 이때는 실행 결과에서 실제 헤더와 Body를 확인해야 한다.

Slack 일부 API나 오래된 사내 시스템은 아직도 x-www-form-urlencoded를 기대하는 경우가 있다. “요즘은 다 JSON 아닌가?”라고 생각하고 넘어가면 이 구간에서 오래 막힌다.

5. 호출은 성공했는데 다음 노드에서 멈추면 응답 파싱을 봐야 한다

n8n API 호출 실패라고 느끼지만, 실제로는 HTTP Request 노드가 200 OK를 받은 뒤 다음 노드에서 멈추는 경우도 많다. 이건 응답이 내가 예상한 구조가 아니기 때문이다. JSON일 줄 알고 다음 노드에서 $json.data.id를 읽었는데, 실제 응답은 XML이거나 배열 구조가 다르면 체감상 호출 실패처럼 보인다.

또 어떤 API는 실패했는데도 200 OK를 보내고, Body 안에 status: error나 success: false를 넣는다. 이런 경우 응답 코드만 보고 통과시키면 다음 노드에서 의도치 않게 멈춘다. 그러니 “응답 코드가 200이면 성공”이라고 단순화하지 말고, 필요한 필드를 IF 노드나 Code 노드에서 한 번 더 체크하는 편이 안전하다.

6. SSL과 자체 서명 인증서는 스테이징 환경에서 특히 자주 발목을 잡는다

상용 SaaS API를 붙일 때는 잘 안 보이지만, 사내 시스템이나 테스트 서버를 붙일 때는 SSL 검증 오류가 자주 나온다. SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_VERIFY_LEAF_SIGNATURE 같은 에러가 대표적이다. 이 경우는 URL도 맞고 인증도 맞는데, 인증서 체인을 신뢰하지 못해서 연결 자체가 거부되는 상황이다.

n8n에서는 노드 옵션에서 인증서 검증을 느슨하게 둘 수 있지만, 이건 어디까지나 임시 확인용으로만 보는 편이 좋다. 운영에서는 가능하면 정식 인증서로 맞추는 것이 안전하다. 서버 전체에서 SSL 검증을 끄는 식의 우회는 영향 범위가 너무 커서 권장하기 어렵다.

n8n API 호출 실패 오류 코드별 트러블슈팅 체크리스트 인포그래픽

7. 운영에서만 실패하면 Rate Limit과 타임아웃을 먼저 의심하는 편이 빠르다

테스트에서는 한두 번 잘 되는데 실제 자동화 돌리기 시작하면 실패하는 API가 있다. 이때 가장 흔한 원인은 429 Too Many Requests와 타임아웃이다. 분당/초당 호출 제한을 넘었거나, 응답이 너무 늦어서 n8n 또는 앞단 프록시가 먼저 연결을 끊는 경우다.

이 문제는 특히 반복 처리나 대량 리스트 순회에서 잘 터진다. SplitInBatches, Wait, 재시도 간격 조절 같은 구조를 넣지 않고 바로 몰아 보내면 테스트에서는 멀쩡해도 운영에서는 무너진다. 타임아웃도 마찬가지다. 외부 API 응답이 원래 느린 편이거나, 이미지 생성·파일 처리처럼 시간이 걸리는 작업이면 HTTP Request 노드 자체 timeout이나 프록시 timeout을 함께 확인해야 한다.

웹훅 경로에서 API 호출이 길어지는 구조라면 [관련 글: n8n 웹훅 타임아웃 404 403 오류 해결 가이드 더 알아보기]와 같이 보면 응답 전략까지 함께 정리하기 좋다.

오류 코드별로 보면 이렇게 정리된다

증상주요 원인먼저 볼 것
400필수 필드 누락, Content-Type 불일치, Body 포맷 오류Request 헤더/Body 실제 전송값
401인증 누락, 키 위치 오류, 토큰 만료Header/Query 위치, Bearer 접두어, Credential 상태
403권한 부족, IP 제한, Scope 부족API 서비스 권한 정책과 접근 제한
404엔드포인트 오타, 버전 변경, 잘못된 리소스 경로실제 요청 URL과 최신 문서
405메서드 불일치GET/POST/PUT/PATCH 재확인
429호출 제한 초과호출 간격, 재시도, 배치 구조
500/502/503상대 서버 장애API 상태 페이지, 일시 재시도
타임아웃응답 지연, 프록시 제한, 네트워크 문제노드 timeout, 프록시 timeout, 느린 단계

빠르게 자가 점검할 때는 이 순서가 좋다

  • 에러 코드가 있는지 먼저 확인한다.
  • Request 내용에서 실제 URL, Header, Body를 본다.
  • 동일 요청을 Postman이나 curl로 재현해본다.
  • n8n 바깥에서도 안 되면 API 서비스 문서·권한·상태 페이지를 본다.
  • n8n에서만 안 되면 Header, Body, Expression, Credential 차이를 집중 점검한다.

결국 가장 빠른 방법은 n8n 안팎을 비교하는 것이다

API 호출 실패를 오래 끄는 가장 흔한 이유는 문제를 n8n 안에서만 찾기 때문이다. 그런데 같은 요청을 Postman이나 curl로 보내봤을 때도 동일하게 실패하면, 그건 n8n이 아니라 API 서비스 설정이나 인증 정보 자체 문제일 가능성이 높다. 반대로 밖에서는 되는데 n8n에서만 안 된다면, 그때는 헤더, Body, Response Format, Expression 차이를 보면서 n8n 쪽 설정을 좁혀가면 된다.

즉, n8n API 호출 실패를 빨리 해결하려면 “무슨 옵션을 더 켤까”보다 “실패 원인이 어느 층에 있나”를 먼저 나눠보는 편이 낫다. URL, 인증, 메서드, Content-Type, 응답 구조, SSL, 호출 제한. 결국 대부분의 문제는 이 안에서 나온다.


참고 자료:
n8n 공식 문서 – HTTP Request Node

Eddy Glen
Eddy Glen

Eddy Glen은 n8n 자동화와 워드프레스 연동, API 기반 업무 자동화를 중심으로 콘텐츠를 운영합니다. 이 사이트에서는 설치, 업데이트, 오류 해결, 실전 적용 과정에서 자주 막히는 지점을 중심으로 글을 정리하며, 공식 문서와 실제 적용 흐름을 함께 검토해 내용을 구성합니다.

기사 : 72