error 지시문

원문 보기 위키 갱신 2026.10.03

error 지시문 (에러 트리거)

error 지시문은 HTTP 핸들러 체인에서 에러를 일으켜요. 선택적으로 메시지와 권장 HTTP 상태 코드를 지정할 수 있어요. 응답 본문을 직접 쓰지 않고, 커스텀 에러 처리 로직을 호출하기 위해 handle_errors 지시문과 함께 쓰는 것을 전제로 해요.

출처: Caddy 공식 문서

본문

선택적인 메시지와 권장 HTTP 상태 코드와 함께 HTTP 핸들러 체인에서 에러를 트리거해요.

이 핸들러는 응답을 쓰지 않아요. 대신 커스텀 에러 처리 로직을 호출하기 위해 handle_errors 지시문과 짝을 이루어 사용해요.

문법 (Syntax)

error [<matcher>] <status>|<message> [<status>] {
    message <text>
}

****는 쓸 HTTP 상태 코드예요. 기본값은 500이에요.
****는 에러 메시지예요. 기본값은 에러 메시지가 없어요.
message는 에러 메시지를 지정하는 또 다른 방법이에요. 여러 줄일 때 편리해요.

정리하면, matcher가 아닌 첫 번째 인자는 3자리 상태 코드이거나 에러 메시지 문자열이에요. 에러 메시지라면 다음 인자가 상태 코드가 될 수 있어요.

예시 (Examples)

특정 요청 경로에서 에러를 트리거하고, handle_errors로 응답을 작성해요:

example.com {
	root /srv

	# 특정 경로에 대해 에러 트리거
    error /private* "Unauthorized" 403
	error /hidden* "Not found" 404

    # HTML 페이지를 서빙해 에러를 처리
    handle_errors {
        rewrite /{err.status_code}.html
		file_server
    }

	file_server
}

더 알아보기 (Learn more)

Caddy 공식 문서