상태·종료 코드 조회
HTTP 상태 코드, Docker·쿠버네티스 종료 코드, 네트워크 errno를 한 곳에서 검색합니다. 항목마다 원인, 바로 실행할 점검 명령, 재시도 가능 여부를 함께 보여 줍니다.
브라우저 안에서만 실행됩니다. 입력한 내용은 어디에도 업로드되지 않습니다.
- 200OK재시도 가능HTTP
요청이 성공했고 응답 본문에 결과가 담겨 있습니다. 200인데 본문이 비어 있다면 캐시나 예외 처리 분기에서 응답한 경우가 많습니다.
curl -i https://example.com/api/healthcurl -sS https://example.com/api/health | head -c 200- 같은 요청을 그대로 다시 보내도 됩니다.
- 201Created재시도 비권장HTTP
요청으로 리소스가 생성되었습니다. Location 헤더가 새 레코드를 가리키며, 이 헤더가 없으면 클라이언트가 후속 요청을 이어가기 어렵습니다.
curl -i -X POST -H 'Content-Type: application/json' -d '{"name":"test"}' https://example.com/api/items- 같은 요청을 반복해도 같은 응답만 돌아옵니다.
- 204No Content재시도 비권장HTTP
요청은 성공했고 응답 본문은 없습니다. 항상 JSON을 파싱하는 코드는 여기서 unexpected end of JSON input 오류를 냅니다.
curl -i -X DELETE https://example.com/api/items/42- 같은 요청을 반복해도 같은 응답만 돌아옵니다.
- 301Moved Permanently재시도 가능HTTP
URL이 영구히 바뀌었고 클라이언트가 리다이렉트를 캐시합니다. 옛 경로가 다시 돌아오지 않을 때만 쓰고, 일시적인 이동은 302나 307을 씁니다.
curl -sSIL https://example.com/old-path- 같은 요청을 그대로 다시 보내도 됩니다.
- 302Found재시도 가능HTTP
일시적 리다이렉트지만 클라이언트가 POST를 GET으로 바꿀 수 있습니다. 메서드를 유지해야 하는 API라면 307이나 308을 쓰세요.
curl -sSIL https://example.com/login- 같은 요청을 그대로 다시 보내도 됩니다.
- 304Not Modified재시도 가능HTTP
캐시본이 아직 유효해서 본문을 보내지 않았습니다. If-None-Match나 If-Modified-Since가 있을 때만 나오며, 로그에서 오류가 아닙니다.
curl -i -H 'If-None-Match: "etag"' https://example.com/page- 같은 요청을 그대로 다시 보내도 됩니다.
- 307Temporary Redirect재시도 가능HTTP
메서드와 본문을 유지하는 일시적 리다이렉트입니다. POST를 다른 URL로 다시 보내야 할 때 맞는 응답입니다.
curl -sSIL -X POST https://example.com/api/old- 같은 요청을 그대로 다시 보내도 됩니다.
- 308Permanent Redirect재시도 가능HTTP
메서드와 본문을 유지하는 영구 리다이렉트입니다. 브라우저가 캐시하므로 대상 URL이 틀리면 되돌리기 어렵습니다.
curl -sSIL https://example.com/old- 같은 요청을 그대로 다시 보내도 됩니다.
- 400Bad Request수정 후 재시도HTTP
서버가 요청을 읽지 못했습니다. 깨진 JSON, 빠진 필수 필드, 잘못된 Content-Type이 대표적이며, 대부분의 프레임워크는 응답 본문에 문제 필드를 알려 줍니다.
curl -i -X POST -H 'Content-Type: application/json' -d '{"name":"test"}' https://example.com/api/itemsecho '{"name":"test"}' | python3 -m json.tool- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 401Unauthorized수정 후 재시도HTTP
인증 정보가 없거나 유효하지 않습니다. Authorization 헤더 누락, 만료된 토큰, 잘못된 스킴이 원인이며 WWW-Authenticate 헤더로 서버가 원하는 방식을 확인하세요.
curl -i -H "Authorization: Bearer $TOKEN" https://example.com/api/mecurl -sSI https://example.com/api/me | grep -i www-authenticate- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 403Forbidden수정 후 재시도HTTP
인증은 됐지만 권한이 없습니다. 역할이나 스코프, 버킷·테이블 정책, IP 허용 목록을 확인하세요. 로그인 후의 403은 토큰이 아니라 권한 문제입니다.
curl -i -H "Authorization: Bearer $TOKEN" https://example.com/api/admin- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 404Not Found재시도 비권장HTTP
경로나 레코드가 없습니다. 라우트, 끝 슬래시, base URL, id를 확인하세요. 프록시가 경로 접두사를 잘라내도 같은 응답이 나옵니다.
curl -sSIL https://example.com/api/items/42curl -sS http://localhost:3000/api- 같은 요청을 반복해도 같은 응답만 돌아옵니다.
- 405Method Not Allowed수정 후 재시도HTTP
라우트는 있지만 이 메서드는 받지 않습니다. POST 전용 엔드포인트에 GET을 보냈거나 프록시·폼이 메서드를 바꾼 경우이며, Allow 헤더에 허용 메서드가 나옵니다.
curl -i -X GET https://example.com/api/items- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 408Request Timeout재시도 가능HTTP
클라이언트가 제한 시간 안에 요청을 다 보내지 못했습니다. 느린 회선에서의 업로드나 클라이언트보다 짧게 잡힌 프록시 타임아웃이 원인입니다.
curl -sS -o /dev/null -w '%{time_total}s\n' https://example.com/api/upload- 같은 요청을 그대로 다시 보내도 됩니다.
- 409Conflict수정 후 재시도HTTP
현재 상태와 충돌합니다. 중복 유니크 키, 한 행에 대한 동시 수정, 낙관적 잠금 버전 불일치가 원인이며, 다시 읽은 뒤 재시도할 만합니다.
curl -i -X POST -H 'Content-Type: application/json' -d '{"email":"a@b.c"}' https://example.com/api/users- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 413Payload Too Large수정 후 재시도HTTP
본문이 서버나 앞단의 한도를 넘었습니다. nginx client_max_body_size, 서버리스 요청 상한, 프레임워크 본문 한도를 확인하고 압축하거나 나눠 올리세요.
du -h ./upload.zipcurl -i -F 'file=@upload.zip' https://example.com/api/upload- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 415Unsupported Media Type수정 후 재시도HTTP
엔드포인트가 받지 않는 Content-Type입니다. JSON 본문을 폼 데이터로 보낸 경우가 흔하니 application/json으로 맞추고 본문도 유효한 JSON으로 보내세요.
curl -i -X POST -H 'Content-Type: application/json' -d '{"a":1}' https://example.com/api/items- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 422Unprocessable Entity수정 후 재시도HTTP
형식은 맞지만 값이 검증을 통과하지 못했습니다. FastAPI, Rails, Laravel 같은 프레임워크가 본문에 필드 오류를 담아 주니 요청 형태를 바꾸기 전에 읽어 보세요.
curl -i -X POST -H 'Content-Type: application/json' -d '{"email":"nope"}' https://example.com/api/users- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 429Too Many Requests재시도 가능HTTP
호출 한도나 할당량에 걸렸습니다. Retry-After를 읽고 지터를 두고 물러나며, IP·API 키·로그인 사용자 중 무엇이 제한됐는지 확인하세요.
curl -sSI https://example.com/api/items | grep -i retry-aftersleep 5 && curl -i https://example.com/api/items- 같은 요청을 그대로 다시 보내도 됩니다.
- 500Internal Server Error재시도 가능HTTP
서버가 처리하지 못한 오류가 났습니다. 스택 트레이스는 서버 로그에 있고, 특정 라우트에서만 나는 500은 네트워크가 아니라 그 핸들러 문제입니다.
curl -i https://example.com/api/itemsdocker compose logs -f --tail 50 api- 같은 요청을 그대로 다시 보내도 됩니다.
- 502Bad Gateway재시도 가능HTTP
프록시가 업스트림에 닿았지만 쓸 만한 응답을 받지 못했습니다. 앱이 죽었거나 재시작 중이거나, 다른 포트에서 듣거나, TLS 포트에 HTTP를 보냈을 때입니다.
curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' https://example.com/docker compose ps- 같은 요청을 그대로 다시 보내도 됩니다.
- 503Service Unavailable재시도 가능HTTP
서버는 살아 있지만 응답할 수 없습니다. 과부하, 점검 모드, 의존 서비스 장애, 로드밸런서 뒤에 건강한 인스턴스가 없는 상태이며 Retry-After가 재시도 시점을 알려 줍니다.
curl -sSI https://example.com/ | grep -i retry-afterdocker compose ps- 같은 요청을 그대로 다시 보내도 됩니다.
- 504Gateway Timeout재시도 가능HTTP
프록시가 업스트림을 기다리다 타임아웃을 넘겼습니다. 코드보다 느린 쿼리, 빠진 인덱스, proxy_read_timeout이나 서버리스 실행 시간 한도를 먼저 보세요.
curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' http://localhost:3000/api/slowpsql "$DATABASE_URL" -c 'EXPLAIN ANALYZE SELECT 1'- 같은 요청을 그대로 다시 보내도 됩니다.
- 0Exit 0 — success재시도 가능컨테이너·종료 코드
프로세스가 성공적으로 끝났습니다. 한 번 돌고 끝나는 작업에는 정상이고, 계속 떠 있어야 하는 서비스에는 잘못된 종료입니다. 진입점이 일을 마치고 종료하는지 확인하세요.
docker logs --tail 50 <container>docker inspect --format '{{.State.ExitCode}}' <container>- 같은 요청을 그대로 다시 보내도 됩니다.
- 1Exit 1 — application error수정 후 재시도컨테이너·종료 코드
애플리케이션 자체가 실패했습니다. 잡히지 않은 예외, 실패한 검증, 빠진 마이그레이션이 원인이며 컨테이너 로그 마지막 줄에 이유가 있습니다.
docker logs --tail 100 <container>docker inspect --format '{{.State.ExitCode}}' <container>- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 2Exit 2 — usage error수정 후 재시도컨테이너·종료 코드
셸 내장 명령이나 명령줄이 잘못됐습니다. 잘못된 플래그, 빠진 인자, 진입점 스크립트에서 읽지 못한 파일이 원인입니다.
docker logs --tail 50 <container>docker run --rm -it --entrypoint sh <image>- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 126Exit 126 — cannot execute수정 후 재시도컨테이너·종료 코드
명령은 있지만 실행할 수 없습니다. 실행 권한 누락, shebang의 윈도우 줄바꿈, 이미지에 없는 인터프리터가 원인입니다.
docker run --rm -it --entrypoint sh <image> -c 'ls -l /entrypoint.sh'file /path/to/entrypoint.sh- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 127Exit 127 — command not found수정 후 재시도컨테이너·종료 코드
이미지 PATH에서 명령을 찾지 못했습니다. 오타, 설치되지 않은 패키지, 멀티스테이지 빌드의 다른 단계에만 있는 바이너리가 원인입니다.
docker run --rm -it --entrypoint sh <image> -c 'command -v node'docker run --rm -it --entrypoint sh <image> -c 'echo $PATH'- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 130Exit 130 — SIGINT재시도 가능컨테이너·종료 코드
Ctrl-C로 멈춘 경우로, 128에 시그널 2를 더한 값입니다. 직접 중단한 컨테이너에는 정상이고, 아무도 건드리지 않았는데 나오면 확인이 필요합니다.
docker inspect --format '{{.State.ExitCode}}' <container>- 같은 요청을 그대로 다시 보내도 됩니다.
- 137Exit 137 — SIGKILL / OOMKilled수정 후 재시도컨테이너·종료 코드
128에 시그널 9를 더한 강제 종료입니다. 대부분 OOM 킬러가 컨테이너를 죽였으므로 한도를 올리기 전에 앱의 최대 메모리 사용량과 한도를 비교하세요.
docker inspect --format '{{.State.OOMKilled}}' <container>docker stats --no-stream <container>kubectl describe pod <pod> | grep -i -A2 'Last State'- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 139Exit 139 — SIGSEGV수정 후 재시도컨테이너·종료 코드
세그멘테이션 오류로 죽었습니다(128+11). 다른 libc용으로 빌드된 네이티브 모듈이나 Node·Python ABI가 맞지 않을 때 흔합니다.
docker logs --tail 100 <container>docker inspect --format '{{.Config.Image}}' <container>- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- 143Exit 143 — SIGTERM재시도 가능컨테이너·종료 코드
정상 종료 신호인 SIGTERM(128+15)을 받았습니다. 스스로 반복된다면 앱이 유예 시간 안에 종료를 마치지 못하고 있다는 뜻입니다.
docker inspect --format '{{.Config.StopTimeout}}' <container>docker logs --tail 50 <container>- 같은 요청을 그대로 다시 보내도 됩니다.
- CrashLoopBackOffKubernetes CrashLoopBackOff수정 후 재시도컨테이너·종료 코드
컨테이너가 계속 종료돼 쿠버네티스가 다시 시작하고, 재시도 간격이 점점 늘어납니다. 직전 시도의 출력에 종료 이유가 있습니다.
kubectl logs <pod> --previous --tail 100kubectl describe pod <pod> | grep -i -A5 'Last State'- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- ImagePullBackOffKubernetes ImagePullBackOff수정 후 재시도컨테이너·종료 코드
이미지를 당기지 못했습니다. 없는 태그, imagePullSecrets 없는 프라이빗 레지스트리, 노드를 제한하는 레지스트리 속도 제한이 원인입니다.
kubectl describe pod <pod> | sed -n '/Events/,$p'kubectl get secret <secret> -o yaml- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- CreateContainerConfigErrorKubernetes CreateContainerConfigError수정 후 재시도컨테이너·종료 코드
컨테이너가 참조하는 것이 없어 만들 수 없습니다. Secret이나 ConfigMap, 그 키 중 하나, 또는 이를 담은 볼륨이 빠졌는지 보세요.
kubectl describe pod <pod> | sed -n '/Events/,$p'kubectl get secret,configmap- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- EvictedKubernetes Evicted수정 후 재시도컨테이너·종료 코드
노드의 메모리·디스크·프로세스 자원이 부족해 파드가 축출됐습니다. 실제 사용량과 맞지 않는 requests/limits, 여유 공간이 없는 노드가 흔한 원인입니다.
kubectl get pod <pod> -o jsonpath='{.status.reason}{"\\n"}{.status.message}{"\\n"}'kubectl describe node <node> | grep -i -A6 'Conditions'- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- ECONNREFUSEDECONNREFUSED재시도 가능네트워크 Errno
그 host와 port에 연결을 받는 프로세스가 없거나, 127.0.0.1에만 열려 있습니다. Docker 안에서는 localhost 대신 서비스 이름을 쓰고 포트는 컨테이너 포트여야 합니다.
nc -vz localhost 3000ss -ltnp | grep 3000docker compose ps- 같은 요청을 그대로 다시 보내도 됩니다.
- ECONNRESETECONNRESET재시도 가능네트워크 Errno
요청 도중 상대가 연결을 끊었습니다. 피어가 죽었거나 타임아웃됐고, 프록시나 로드밸런서가 유휴 연결을 정리했거나, TLS 포트에 HTTP를 보낸 경우입니다.
curl -v https://example.com/api/itemscurl -v --http1.1 --keepalive-time 30 https://example.com/- 같은 요청을 그대로 다시 보내도 됩니다.
- ETIMEDOUTETIMEDOUT재시도 가능네트워크 Errno
제한 시간 안에 응답이 오지 않았습니다. 라우팅, 방화벽·보안 그룹, 잘못된 호스트, 너무 느린 피어가 원인이며 코드를 고치기 전에 포트부터 확인하세요.
nc -vz -w 5 <host> 443curl -sS -o /dev/null -w '%{time_connect}s %{time_total}s\n' https://example.com/- 같은 요청을 그대로 다시 보내도 됩니다.
- ENOTFOUNDENOTFOUND수정 후 재시도네트워크 Errno
호스트 이름이 해석되지 않았습니다. 오타, 빠진 서치 도메인, DNS가 없는 컨테이너, 리졸버의 속도 제한이 원인입니다.
getent hosts api.example.comnslookup api.example.com 1.1.1.1- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- EADDRINUSEEADDRINUSE수정 후 재시도네트워크 Errno
이 머신에서 포트가 이미 사용 중입니다. 다른 프로세스나 끝나지 않은 이전 인스턴스가 잡고 있습니다.
lsof -i :3000kill -15 $(lsof -t -i :3000)- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
- EACCESEACCES수정 후 재시도네트워크 Errno
권한이 거부됐습니다. 권한 없이 1024 미만 포트를 열었거나, 프로세스가 쓸 수 없는 파일·디렉터리입니다. 컨테이너에서는 non-root 사용자와 root 소유 볼륨 조합이 흔합니다.
idls -ld /var/lib/appPORT=8080 node server.js- 원인을 고친 뒤 재시도하세요. 지금 다시 보내면 결과는 같습니다.
상태·종료 코드 참고
빠른 참조- 4xx vs 5xx
- 4xx는 고칠 요청이 클라이언트에 있다는 뜻이고 5xx는 서버 실패입니다. 한 라우트에서만 나는 502·504는 보통 프록시 뒤 업스트림 문제입니다.
- 128 + signal
- 셸은 시그널로 종료된 프로세스를 128에 시그널 번호를 더해 보고합니다. 137은 128+9(SIGKILL), 143은 128+15(SIGTERM), 139는 128+11(SIGSEGV)입니다.
- OOMKilled
- docker inspect에서 OOMKilled가 true인 137은 메모리 한도에 닿았다는 뜻입니다. 앱 최대 사용량보다 낮은 한도는 같은 방식으로 계속 재시작시킵니다.
- CrashLoopBackOff
- 컨테이너가 계속 종료돼 쿠버네티스가 다시 시작하는 상태입니다. kubectl logs --previous로 실패한 시도를 확인하세요.
- ECONNREFUSED
- 그 host와 port에서 듣는 프로세스가 없습니다. Docker 안에서는 호스트가 localhost가 아니라 서비스 이름이고, 포트도 컨테이너 포트입니다.
- Retry-After
- 429나 503이 언제 다시 오면 되는지 알려 주는 헤더입니다. 짧은 간격으로 반복하지 말고 지터를 두고 물러나세요.
자주 묻는 질문
도구 아래에서 답을 확인하세요컨테이너가 137로 끝났습니다. 무슨 뜻인가요?
137은 128+9, SIGKILL입니다. 메모리 부족 킬러이거나 docker stop입니다. docker inspect의 OOMKilled로 구분하세요.
CrashLoopBackOff는 무슨 상태인가요?
컨테이너가 계속 종료돼 쿠버네티스가 다시 시작하는 상태입니다. kubectl logs --previous로 마지막 시도의 원인을 보세요.
503은 재시도해도 되나요?
지터를 두고 재시도하세요. 보통 일시적인 업스트림이나 용량 문제이며 Retry-After가 기다릴 시간을 알려 줍니다.
Linux 관련 문법 가이드
Linux 가이드 전체Linux: Too many open files (EMFILE) and ulimit
EMFILE is a per-process descriptor limit, ENFILE is the kernel's. Read the limit from /proc, raise it in the right layer, and find the leak that made it matter.
Linuxsystemd status=203/EXEC and 217/USER: Exec and Permission Failures
203 is a failed execve, 217 is a user systemd could not resolve. Both happen before your program runs, and the check that finds each takes one command.
Linuxsystemd Timers vs Cron: Missing PATH, Overlapping Runs, Time Drift
Cron runs a bare shell with no profile and no locking, and systemd reads the system time zone. The environment, single-instance and schedule fixes for both.
LinuxBash Indexed Arrays, Associative Maps, and Parameter Expansion
Quoting decides whether an array stays a list, and the expansion operators replace most external text tools. Includes set -u, mapfile, namerefs, and the bash 3.2 differences that break scripts on macOS.