405 Method Not Allowed

서버는 여러분의 요청을 완벽하게 이해했습니다. 다만 그 방식으로는 처리하지 않겠다는 것입니다.

405 Method Not Allowed가 바로 그런 의미입니다. 엔드포인트는 존재합니다. 서버는 여러분이 요청한 것을 인식했습니다. 하지만 여러분이 사용한 HTTP 메서드—DELETE, POST, PUT, 무엇이든—는 이 엔드포인트가 허용하지 않는 것입니다. 올바른 문을 두드렸지만, 잘못된 질문을 한 것입니다.

405의 구조

405에 부딪히면, 응답은 무엇이 잘못되었고 어떻게 고쳐야 하는지 알려줍니다:

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST
Content-Type: application/json

{
    "error": "Method Not Allowed",
    "message": "DELETE method is not supported for this endpoint",
    "allowedMethods": ["GET", "POST"]
}

Allow 헤더는 선택적인 장식이 아닙니다—HTTP 명세에 의해 필수입니다. 서버는 어떤 메서드를 허용하는지 알려줘야 합니다. 이것은 서버가 친절하게 말하는 것입니다: "여기서는 DELETE할 수 없지만, GET이나 POST는 가능합니다."

엔드포인트가 메서드를 거부하는 이유

일부 엔드포인트는 설계상 읽기 전용입니다:

POST /api/status HTTP/1.1

HTTP/1.1 405 Method Not Allowed
Allow: GET

상태 엔드포인트는 정보를 보고하기 위해 존재하지, 받기 위해 존재하지 않습니다. 여기서 POST는 의미가 없습니다.

일부 리소스는 API를 통해 삭제되어서는 안 됩니다:

DELETE /api/users HTTP/1.1

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

사용자를 조회(GET)하고 생성(POST)할 수 있지만, 일괄 삭제는 노출되지 않습니다. 안전 조치일 수도 있고, 다른 프로세스를 통해 삭제가 이루어질 수도 있습니다. 엔드포인트는 자신의 목적에 맞는 작업이 무엇인지 결정합니다.

네 가지 거절 방식

HTTP에는 거절을 표현하는 여러 방식이 있으며, 각각 의미가 다릅니다:

404 Not Found: "무슨 말인지 모르겠습니다."

GET /api/nonexistent
HTTP/1.1 404 Not Found

엔드포인트가 전혀 존재하지 않습니다.

405 Method Not Allowed: "원하는 것은 알지만, 그 방식으로는 하지 않겠습니다."

DELETE /api/users
HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

엔드포인트는 존재하지만 이 메서드를 허용하지 않습니다.

403 Forbidden: "특별히 당신에게 이것이 허용되지 않습니다."

DELETE /api/users/123
HTTP/1.1 403 Forbidden

메서드는 유효할 수 있지만, 권한이 없습니다.

501 Not Implemented: "그 메서드가 무엇인지조차 모릅니다."

WEIRDMETHOD /api/users
HTTP/1.1 501 Not Implemented

서버가 HTTP 메서드 자체를 인식하지 못합니다.

이 구분은 디버깅에 중요합니다. 404는 URL을 확인하라는 뜻입니다. 405는 메서드를 확인하라는 뜻입니다. 403은 권한을 확인하라는 뜻입니다. 501은 아마도 표준을 벗어난 무언가를 시도하고 있다는 뜻입니다.

405를 올바르게 구현하기

패턴은 간단합니다—지원하는 메서드를 정의하고, 나머지는 거부합니다:

app.route('/api/users')
    .get(function(request, response) {
        response.json(users);
    })
    .post(function(request, response) {
        createUser(request.body);
        response.status(201).json({success: true});
    })
    .all(function(request, response) {
        response.status(405)
            .set('Allow', 'GET, POST, OPTIONS')
            .json({
                error: 'Method Not Allowed',
                allowedMethods: ['GET', 'POST', 'OPTIONS']
            });
    });

.all() 핸들러는 위에서 명시적으로 정의되지 않은 모든 메서드를 처리합니다. 모든 405 응답에는 Allow 헤더가 포함됩니다—이것은 단순한 좋은 관행이 아니라 필수 사항입니다.

OPTIONS를 잊지 마세요

OPTIONS 메서드는 "여기서 무엇을 할 수 있나요?"라고 묻습니다. 서버는 반드시 답해야 합니다:

OPTIONS /api/users HTTP/1.1

HTTP/1.1 204 No Content
Allow: GET, POST, PUT, DELETE, OPTIONS

이것이 CORS 사전 요청이 작동하는 방식입니다—브라우저는 교차 출처 요청을 하기 전에 OPTIONS를 먼저 보냅니다. 서버가 OPTIONS에 405를 반환하면, 브라우저에서 API를 사용하려는 클라이언트의 CORS가 깨집니다.

클라이언트로서 405 처리하기

405를 받으면, Allow 헤더가 대신 무엇을 해야 하는지 알려줍니다:

async function makeRequest(url, method, data) {
    const response = await fetch(url, {
        method: method,
        headers: { 'Content-Type': 'application/json' },
        body: data ? JSON.stringify(data) : undefined
    });

    if(response.status === 405) {
        const allowHeader = response.headers.get('Allow');
        const allowedMethods = allowHeader ? allowHeader.split(', ') : [];
        
        throw new Error(
            `${method} not allowed. Try: ${allowedMethods.join(', ')}`
        );
    }

    return response;
}

RESTful 메서드의 의미와 역할

REST에서 각 메서드는 고유한 의미를 가집니다:

• GET: 리소스 조회 (안전하고 멱등적)
• POST: 새 리소스 생성
• PUT: 리소스 전체 교체 (멱등적)
• PATCH: 리소스 부분 업데이트
• DELETE: 리소스 제거 (멱등적)

엔드포인트는 의미적으로 적합한 메서드만 허용해야 합니다:

// 컬렉션: 조회 및 생성
app.route('/api/users')
    .get(listUsers)
    .post(createUser)
    .all(methodNotAllowed(['GET', 'POST', 'OPTIONS']));

// 개별 리소스: 읽기, 업데이트, 삭제
app.route('/api/users/:id')
    .get(getUser)
    .put(replaceUser)
    .patch(updateUser)
    .delete(deleteUser)
    .all(methodNotAllowed(['GET', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']));

컬렉션 전체를 DELETE할 수는 없습니다 (그것은 위험합니다). 특정 리소스에 POST할 수도 없습니다 (POST는 새로운 것을 생성하는 역할이지, 기존 것을 수정하는 것이 아닙니다). 이러한 제한은 임의적인 것이 아닙니다—REST가 예측 가능한 동작을 유지하는 방식입니다.

405 Method Not Allowed 자주 묻는 질문

엔드포인트가 확실히 존재하는데 왜 405가 발생하나요?

그것이 바로 405의 의미입니다—엔드포인트는 존재하지만, 사용 중인 HTTP 메서드를 허용하지 않습니다. 응답의 Allow 헤더를 확인하여 어떤 메서드가 지원되는지 살펴보고, 요청을 그에 맞게 조정하세요.

Allow 헤더가 정말 필수인가요?

그렇습니다. RFC 7231에 따르면 405 응답에는 대상 리소스가 지원하는 메서드를 나열하는 Allow 헤더가 "반드시" 포함되어야 합니다. 이를 생략하면 HTTP 명세를 위반하고 클라이언트 입장에서 디버깅이 더 어려워집니다.

존재하지만 핸들러가 없는 엔드포인트에 대해 404와 405 중 무엇을 반환해야 하나요?

URL 패턴이 애플리케이션의 라우트와 일치한다면, 지원하는 메서드와 함께 405를 반환하세요 (OPTIONS만이라도). URL 자체가 시스템의 어떤 리소스와도 대응하지 않을 때만 404를 반환하세요.

405는 CORS와 어떻게 상호작용하나요?

브라우저는 특정 메서드를 사용하는 교차 출처 요청 전에 OPTIONS 사전 요청을 먼저 보냅니다. 서버가 OPTIONS에 405를 반환하면, 사전 요청이 실패하고 실제 요청은 전혀 이루어지지 않습니다. Allow 헤더만 반환하더라도 OPTIONS 요청은 반드시 처리해야 합니다.