HTTP 헤더

HTTP 헤더는 클라이언트와 서버 간의 HTTP 요청과 응답에서 추가 정보를 전달하는 데 사용돼요. 이 정보에는 요청의 유형(Content-Type), 응답의 유형(Accept), 인증 정보(Authorization), 캐싱 제어(Cache-Control, ETag, Last-Modified) 등 다양한 메타데이터가 포함되죠.

HTTP 헤더는 이름-값 쌍 형식이라 {HTTP_HEADER_KEY}: {HTTP_HEADER_VALUE} 형식으로 쓰는데요. 예를 들어 볼게요. 토스페이먼츠 API의 모든 필드와 오류 메시지는 기본적으로 한글로 제공돼요. 만약 응답을 영문으로 받고 싶다면 요청 헤더에 Accept-Language: en-US를 포함하면 간단히 해결됩니다. 팝업 차단 에러를 방지하기 위한 헤더도 사용할 수 있는데요. 결제 과정에서 팝업 차단 에러가 나는 것을 방지하기 위해 COOP(Cross-Origin-Opener-Policy) 헤더를 Cross-Origin-Opener-Policy: same-origin-allow-popups와 같이 포함할 수 있어요.

이렇게 표준 HTTP 헤더 외에도 토스페이먼츠에서는 에러 시나리오를 테스트를 할 때 사용할 수 있는 커스텀 HTTP 헤더를 제공하는데요. 커스텀 HTTP 헤더는 개발자가 직접 정의해서 사용하는 HTTP 헤더입니다.

표준 HTTP 헤더가 아니라 특정 서비스에서만 사용되는 추가 정보를 전달하기 위해 사용하죠. 표준 HTTP 헤더와 마찬가지로 서버는 클라이언트로부터 받은 커스텀 헤더를 바탕으로 특정 동작을 수행하거나, 클라이언트에게 필요한 추가 정보를 제공하기 위해 커스텀 헤더를 사용할 수 있어요. 클라이언트 입장에서는 서버에게 특정 요청을 보낼 때 커스텀 헤더를 사용하여 추가 정보를 제공하거나, 서버의 응답에서 커스텀 헤더를 통해 받은 정보를 활용할 수 있어요. 사용은 표준 HTTP 헤더와 마찬가지로 헤더의 이름과 값을 지정해서 요청 또는 응답에 포함시키면 됩니다.

과거에 커스텀 HTTP 헤더의 이름은 X-로 시작하는 것이 일반적으로 권장되었어요. X-는 표준화되지 않은 헤더라는 것을 나타냈기 때문이에요. 그런데 최신 HTTP 표준에서는 이 방식을 지원 중단(Deprecated) 하기로 했어요. 즉, X- 없이도 사용자 정의 헤더를 정의할 수 있어요.

예를 들어 My-Custom-Header라는 이름의 커스텀 헤더를 사용하려면 X-My-Custom-Header가 아니라 아래와 같이 만들어서 사용하면 돼요.

커스텀 HTTP 헤더를 사용할 때는 헤더 이름이 충돌하지 않도록 주의해야 해요. 특히 다른 표준 헤더와 이름이 겹치지 않도록 하는 것이 좋아요. 헤더 이름을 명확하고 식별 가능하게 지정하거나, 접두사를 사용하는 것도 좋아요. 토스페이먼츠에서는 Tosspayments라는 접두사를 붙였어요.

토스페이먼츠에서는 커스텀 HTTP 헤더를 이용해서 에러 시나리오를 테스트할 수 있도록 했어요. 이 헤더를 이용하면 라이브 환경에서 나는 에러를 연동 과정에서 미리 발생시키고, 해당 에러 시나리오에 맞는 처리를 추가할 수 있어요. 다양한 에러 케이스를 미리 테스트해 볼 수 있으니 편리해요. 에러 테스트용 커스텀 HTTP 헤더는 테스트 키를 사용할 때만 적용되고, 라이브 환경에서는 테스트 코드 헤더가 무시돼요.

테스트 환경에서 에러를 재현하는 방법을 알려드릴게요. 아래와 같이 TossPayments-Test-Code 헤더를 추가하고, {TEST_CODE} 값으로 테스트하고 싶은 에러 코드를 넣고 API를 실행하면 됩니다.

예를 들어, 카드 번호 결제 API에 잘못된 유효기간을 넣었을 때 돌아오는 응답을 보고 싶다면 아래와 같이 INVALID_CARD_EXPIRATION를 테스트 헤더에 추가하세요.