Skip to content

웹훅 및 연결된 콘텐츠 요청 문제 해결

이 문서에서는 웹훅 및 연결된 콘텐츠의 일반적인 오류 코드를 문제 해결하는 방법을 다루고, 이러한 오류가 요청에서 어떻게 발생할 수 있는지에 대한 추가 설명을 제공합니다.

4XX 오류 {#4xx-errors}

4XX 오류는 엔드포인트로 전송된 요청에 문제가 있음을 나타냅니다. 이러한 오류는 일반적으로 잘못된 형식의 매개변수, 누락된 인증 헤더 또는 잘못된 URL을 포함한 잘못된 요청으로 인해 발생합니다. 이러한 오류는 보고서 빌더에도 적용됩니다.

오류 코드 세부 정보 및 해결 단계는 다음 표를 참조하세요:

4XX 오류
오류 코드 의미 해결 단계
400 Bad Request 요청에 잘못된 구문이 있습니다.
  • 요청 페이로드에 구문 오류가 없는지 확인합니다.
  • 모든 필수 필드가 포함되어 있고 올바른 형식인지 확인합니다.
  • JSON 페이로드를 전송하는 경우 JSON 구조를 검증합니다.
  • Liquid를 사용하여 웹훅 요청에 개인화 태그를 템플릿으로 적용하는 경우, Liquid가 빈 값으로 확인되거나 JSON을 깨뜨리는 문자(이스케이프되지 않은 따옴표 등)를 생성하지 않는지 확인합니다. 테스트 사용자에 대해 메시지를 미리보기하여 렌더링된 출력이 유효한지 확인합니다.
401 Unauthorized 요청에 사용자 인증이 필요합니다.
  • 올바른 인증 자격 증명(API 키 또는 토큰 등)이 요청 헤더에 포함되어 있는지 확인합니다.
  • 엔드포인트에 접근할 수 있는 사용자 권한이 있는지 확인합니다.
403 Forbidden 엔드포인트가 요청을 이해하지만 승인을 거부합니다.
  • API 키 또는 토큰에 필요한 권한이 있는지 확인합니다.
  • 엔드포인트에 접근할 수 있는 사용자 권한이 있는지 확인합니다.
404 Not Found 엔드포인트가 요청된 리소스를 찾을 수 없습니다.
  • 엔드포인트 URL에 오타나 잘못된 경로가 없는지 확인합니다.
  • 접근하려는 리소스가 존재하는지 확인합니다.
405 Method Not Allowed 요청 메서드가 엔드포인트에 알려져 있지만 대상 리소스에서 지원되지 않습니다.
  • 요청에 사용된 HTTP 메서드(DELETE, GET, POST, PUT)를 확인합니다.
  • 엔드포인트가 사용 중인 메서드를 지원하는지 확인합니다.
408 Request Timeout 엔드포인트가 요청 처리 중 시간이 초과되었습니다.
  • 요청에 사용된 HTTP 메서드(DELETE, GET, POST, PUT)를 확인합니다.
  • 엔드포인트가 사용 중인 메서드를 지원하는지 확인합니다.
409 Conflict 리소스의 현재 상태와 충돌하여 요청이 완료되지 않았습니다.
  • 요청에 사용된 HTTP 메서드(DELETE, GET, POST, PUT)를 확인합니다.
  • 엔드포인트가 사용 중인 메서드를 지원하는지 확인합니다.
429 Too Many Requests 주어진 시간 내에 너무 많은 요청이 전송되었습니다.
  • Campaign 또는 캔버스 단계의 사용량 제한을 낮추세요.

5XX 오류 {#5xx-errors}

5XX 오류는 엔드포인트에 문제가 있음을 나타냅니다. 이러한 오류는 일반적으로 서버 측 문제로 인해 발생합니다.

오류 코드 의미
500 Internal Server Error 엔드포인트가 요청을 완료하지 못하게 하는 예기치 않은 상태를 만났습니다.
502 Bad Gateway 엔드포인트가 업스트림 서버로부터 잘못된 응답을 받았습니다.
503 Service Unavailable 엔드포인트가 일시적인 과부하 또는 유지보수로 인해 현재 요청을 처리할 수 없습니다.
504 Gateway Timeout 엔드포인트가 업스트림 서버로부터 적시에 응답을 받지 못했습니다.
529 Host Overloaded 엔드포인트 호스트가 과부하 상태이며 응답할 수 없습니다.
598 Host Unhealthy 엔드포인트 호스트가 일시적으로 비정상으로 표시되어 Braze가 응답을 시뮬레이션했습니다. 자세한 내용은 비정상 호스트 감지를 참조하세요.
599 Connection Error Braze가 엔드포인트에 연결을 설정하는 동안 네트워크 연결 시간 초과 오류가 발생했으며, 이는 엔드포인트가 불안정하거나 다운되었을 수 있음을 의미합니다.

5XX 오류 해결

다음은 일반적인 5XX 오류를 문제 해결하기 위한 팁입니다:

  • 메시지 활동 로그에서 사용 가능한 구체적인 세부 정보를 오류 메시지에서 확인합니다. 웹훅의 경우 Braze 홈 페이지의 Performance Over Time 섹션으로 이동하여 웹훅 통계를 선택합니다. 여기에서 오류가 발생한 시점을 나타내는 타임스탬프를 찾을 수 있습니다.
  • 엔드포인트를 과부하시키는 너무 많은 요청을 보내고 있지 않은지 확인합니다. 배치로 전송하거나 사용량 제한을 조정하여 오류가 줄어드는지 확인할 수 있습니다.

비정상 호스트 감지

Braze 웹훅 및 연결된 콘텐츠는 대상 호스트가 상당한 속도 저하 또는 과부하로 인해 시간 초과, 너무 많은 요청 또는 Braze가 대상 엔드포인트와 성공적으로 통신하지 못하게 하는 기타 결과를 초래하는 높은 비율의 문제를 경험할 때 이를 감지하는 비정상 호스트 감지 메커니즘을 사용합니다. 이는 대상 호스트에 어려움을 줄 수 있는 불필요한 부하를 줄이기 위한 안전장치 역할을 합니다. 또한 Braze 인프라를 안정화하고 빠른 메시징 속도를 유지하는 데 도움이 됩니다.

감지 임계값은 웹훅과 연결된 콘텐츠 간에 다릅니다:

  • 웹훅의 경우: 1분 이동 시간 창에서 실패 횟수가 3,000건을 초과하면(호스트 이름과 앱 그룹의 고유 조합 기준—엔드포인트 경로 기준이 아님), Braze가 대상 호스트에 대한 요청을 1분 동안 일시적으로 중단합니다.
  • 연결된 콘텐츠의 경우: 1분 이동 시간 창에서 실패 횟수가 3,000건을 초과하고 오류율이 90%를 초과하면(호스트 이름과 앱 그룹의 고유 조합 기준—엔드포인트 경로 기준이 아님), Braze가 대상 호스트에 대한 요청을 1분 동안 일시적으로 중단합니다.

요청이 중단되면 Braze는 비정상 상태를 나타내기 위해 598 오류 코드로 응답을 시뮬레이션합니다. 1분 후 호스트가 정상으로 확인되면 Braze는 전체 속도로 요청을 재개합니다. 호스트가 여전히 비정상이면 Braze는 다시 시도하기 전에 1분 더 기다립니다.

다음 오류 코드가 비정상 호스트 감지기 실패 횟수에 기여합니다: 408, 429, 502, 503, 504, 529.

웹훅의 경우 Braze는 비정상 호스트 감지기에 의해 중단된 HTTP 요청을 자동으로 재시도합니다. 이 자동 재시도는 지수 백오프를 사용하며 실패하기 전에 몇 번만 재시도합니다. 웹훅 오류에 대한 자세한 내용은 오류, 재시도 로직 및 시간 초과를 참조하세요.

연결된 콘텐츠의 경우, 대상 호스트에 대한 요청이 비정상 호스트 감지기에 의해 중단되면 Braze는 오류 응답 코드를 받은 것처럼 메시지를 계속 렌더링하고 Liquid 로직을 따릅니다. 이러한 연결된 콘텐츠 요청이 비정상 호스트 감지기에 의해 중단될 때 재시도되도록 하려면 :retry 옵션을 사용하세요. :retry 옵션에 대한 자세한 내용은 연결된 콘텐츠 재시도를 참조하세요.

비정상 호스트 감지가 문제를 일으키고 있다고 생각되면 Braze 고객지원에 문의하세요.

자동 이메일 및 메시지 활동 로그 항목

자동 이메일 설정

워크스페이스에서 24시간 동안 100,000건 이상의 웹훅 또는 연결된 콘텐츠 엔드포인트 오류(재시도 포함)가 발생하면, Braze는 오류 해결 방법에 대한 다음 정보가 포함된 이메일을 보냅니다.

  • 워크스페이스 이름
  • Canvas 또는 Campaign 링크
  • 엔드포인트 URL
  • 오류 코드
  • 오류가 마지막으로 관찰된 시간
  • 메시지 활동 로그 및 관련 설명서 링크

엔드포인트 오류는 다음과 같습니다:

  • 4XX: 400, 401, 403, 404, 405, 408, 409, 429
  • 5XX: 500, 502, 503, 504, 598, 599

이 이메일은 워크스페이스 수준에서 하루에 한 번만 전송됩니다. 이 이메일에 등록한 사용자가 없으면 Braze는 모든 회사 관리자에게 알립니다.

이 이메일을 수신하도록 등록하려면 다음을 수행하세요:

  1. 설정 > 관리자 설정 > 알림 환경설정으로 이동합니다.
  2. Canvas & Campaigns 섹션에서 Connected Content Errors 및 Webhook Errors를 선택합니다.

메시지 활동 로그 항목

실패가 발생하면 이와 관련된 항목이 메시지 활동 로그에 하나 이상 있습니다. 요청이 재시도되어 최종적으로 성공하면 해당 세부 정보는 Currents 및 Snowflake 데이터 공유에서 확인할 수 있습니다. 재시도 후 요청이 최종적으로 성공하더라도 오류는 여전히 자동 이메일을 트리거할 수 있습니다.

Braze 커런츠의 추가 실패 인사이트

웹훅 관련 문제에 대한 투명성을 높이기 위해 Braze는 상세한 웹훅 실패 이벤트를 Currents 및 Snowflake 데이터 공유로 스트리밍합니다. 이러한 이벤트에는 실패한 웹훅 요청(HTTP 4xx 또는 5xx 응답 등)이 포함되어 웹훅 문제가 메시지 전달에 어떤 영향을 미칠 수 있는지에 대한 더 많은 가시성을 제공합니다. 실패 이벤트에는 최종 오류뿐만 아니라 재시도 중인 오류도 포함됩니다.

자세한 내용은 메시지 참여 이벤트 용어집을 참조하세요.
New Stuff!