401 vs 403 vs 404 차이: API 오류별 의미

401 Unauthorized는 요청에 유효한 자격 증명이 없다는 뜻입니다. 아예 보내지 않았거나, 보낸 자격 증명의 형식이 잘못됐거나, 만료됐거나, 폐기된 경우입니다. 403 Forbidden은 서버가 요청을 이해했지만 거부한다는 뜻으로, 자격 증명을 보냈더라도 그것으로는 부족합니다. 404 Not Found는 그 주소에 아무것도 없거나, 무언가 있다는 사실을 서버가 밝히지 않겠다는 뜻입니다.

HTTP 정의는 RFC 9110에서, bearer 토큰 규칙은 RFC 6750에서 인용했습니다. 예시로 든 Sume API의 내용은 인증, 오류와 비용 (영문), 오류와 요청 한도 (영문) 문서와, 따로 표시한 곳은 현재 코드에서 가져왔습니다. 모두 2026-09-28에 확인했습니다.

401과 403의 차이는 무엇인가요?

401은 자격 증명의 문제이고, 403은 권한의 문제입니다. RFC 9110에 따르면 401을 받은 클라이언트는 새 Authorization 헤더나 교체한 헤더로 요청을 다시 보낼 수 있습니다. 403을 받은 뒤에는 같은 자격 증명으로 요청을 자동으로 반복하지 않아야 하지만, 다른 자격 증명으로 시도할 수는 있습니다. 또한 요청은 자격 증명과 무관한 이유로도 금지될 수 있습니다.

Authorization: Bearer 토큰의 명세인 RFC 6750도 같은 곳에 선을 긋습니다. 만료됐거나 폐기됐거나 형식이 잘못된 토큰에는 오류 코드 invalid_token을 담은 401로 응답해야 합니다. 토큰이 부여한 것보다 높은 권한이 필요한 요청에는 insufficient_scope를 담은 403으로 응답해야 합니다.

API는 왜 403 대신 404를 반환하나요?

리소스가 존재한다는 사실을 확인해 주지 않기 위해서입니다. RFC 9110은 금지된 리소스를 "숨기고" 싶은 서버가 403 대신 404로 응답하도록 허용합니다. 그래서 실제로 있다고 알고 있는 ID에서 404가 나오면, ID만큼이나 자격 증명이 원인일 수 있습니다.

Sume API도 이런 방식으로 ID를 숨깁니다. 문서는 404 not_found를 현재 워크스페이스에 없는 리소스로 정의하고, 다른 소유자의 Format 실행은 존재하지 않는 실행과 똑같이 보입니다. 각 경우는 API가 404를 반환하는 이유에 정리되어 있습니다. 그렇다고 권한 문제까지 이렇게 숨기지는 않습니다. Formats API에서 스코프가 없는 키는 403 insufficient_scope를 받으며, 404 format_not_found를 받는 일은 없습니다.

401이나 403은 어떻게 고치나요?

401이면 자격 증명을 고치세요. API 문서에 나온 헤더와 스킴으로 보내고, 만료됐거나 폐기됐다면 교체하세요. 403이면 자격 증명은 받아들여졌지만 그 작업은 허용되지 않은 것이므로, 대개 그 작업이 허용된 자격 증명을 쓰거나 그 자격 증명으로 허용된 요청을 보내야 합니다.

Sume API에서는 오류 본문이 문제를 짚어 줍니다. 401의 error.code는 unauthorized이고, 현재 코드에서는 Send only one API key credential.처럼 키나 헤더의 무엇이 잘못됐는지 밝히는 메시지가 함께 옵니다. 메시지별 해결법은 curl Bearer 토큰에 정리되어 있습니다. 스코프가 없어서 나는 403 insufficient_scope는 없는 스코프를 details.required_scope에 밝히며, 스코프는 키를 만들 때 고정되므로 해결책은 새 키입니다. 키 오류 전체 표는 Sume API 키 동작 방식에 있습니다.

401, 403, 404는 재시도해야 하나요?

그대로는 안 됩니다. 셋 다 기다리는 것만으로는 대개 풀리지 않고, 자격 증명이나 키, 주소를 바꿔야 합니다. Sume의 오류 본문도 그렇게 알려 줍니다. 현재 코드에서 401, 403 insufficient_scope, 403 workspace_key_required는 retryable: false, next_action: authenticate로 돌아오고, 404는 retryable: false, next_action: fix_input으로 돌아옵니다.

Sume 문서는 403 insufficient_scope를 루프에서 재시도하는 것을 Formats API에서 가장 흔하고 가장 비싼 실수로 꼽습니다. Formats API에서 생성 시점의 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻입니다.

내 API는 어떤 상태 코드를 반환해야 하나요?

요청에 유효한 자격 증명이 없으면 WWW-Authenticate 헤더와 함께 401을 보내세요. RFC 9110에 따르면 401을 생성하는 서버는 챌린지를 하나 이상 담은 이 헤더를 반드시 보내야 합니다. 자격 증명은 유효하지만 그 작업에 충분하지 않으면 403을, 리소스가 없거나 리소스를 숨기기로 했다면 404를 보내세요.

bearer 토큰에 대해서는 RFC 6750이 따라 할 만한 규칙을 하나 더 둡니다. 요청에 인증 정보가 전혀 없으면 401에 오류 코드나 다른 오류 정보를 넣지 않아야 합니다.