API 오류 및 응답
이 참고 문서에서는 Braze API를 사용하는 동안 발생할 수 있는 다양한 오류 및 서버 응답과 문제 해결 방법에 대해 설명합니다.
서버 응답
POST 페이로드가 서버에서 수락되면 성공한 메시지에 대해 다음과 같은 응답이 반환됩니다.
{
"message" : "success"
}
성공은 RESTful API 페이로드가 올바르게 구성되어 푸시 알림, 이메일 또는 기타 메시징 서비스로 전달되었다는 의미일 뿐입니다. 메시지가 실제로 전달되었다는 의미는 아닙니다. 다른 요인 때문에 메시지가 전달되지 않을 수 있기 때문입니다. 예를 들어 기기가 오프라인 상태이거나, Apple 서버에서 푸시 토큰을 거부하거나, 알 수 없는 사용자 ID를 제공했을 수 있습니다.
메시지가 전달되지 않았는데 요청이 성공을 반환하는 이유는 무엇인가요?
message: success 또는 2XX 응답은 Braze가 해당 엔드포인트에 대한 요청을 수락하고 대기열에 넣었다는 의미입니다. 모든 수신자가 메시지를 받았다는 의미는 아닙니다. 메시징의 경우 전달 여부는 여전히 채널 자격 요건, 토큰, 공급자 오류, 콘텐츠 유효성 검사에 따라 달라집니다. 발송을 차단하는 HTTP 오류는 심각한 오류 표를 참조하고, 이후 단계의 전송 측정기준은 Campaign 또는 Canvas 분석을 확인하세요.
메시지를 보내지 않는 /users/identify와 같은 엔드포인트의 경우, 성공 응답은 Braze가 처리를 위해 요청을 수락했다는 의미일 뿐입니다. 제공된 별칭을 가진 사용자가 없거나, 별칭이 이미 external_id가 있는 프로필에 속한 경우 Braze는 식별을 건너뜁니다. 이때도 API는 처음에 성공 응답을 반환하며, 별칭이 일치하지 않았음을 알리는 오류는 없습니다. alias_name은 대소문자를 구분하므로 대소문자가 일치하지 않는 경우에도 같은 결과가 발생합니다.
메시지가 성공했지만 심각하지 않은 오류가 있는 경우 다음과 같은 응답을 받습니다.
{
"message" : "success", "errors" : [<minor error message>]
}
성공한 경우, errors 배열의 오류에 영향을 받지 않은 메시지는 여전히 전달됩니다. 메시지에 심각한 오류가 있는 경우 다음과 같은 응답을 받습니다.
{
"message" : <fatal error message>, "errors" : [<minor error message>]
}
추적된 전송 ID에 대한 응답
Campaign에 대한 분석은 항상 제공됩니다. 또한 Campaign이 브로드캐스트로 전송되는 경우 특정 Campaign 전송 인스턴스에 대한 분석도 제공됩니다. 특정 Campaign 전송 인스턴스에 대한 추적이 가능한 경우 다음과 같은 응답을 받게 됩니다.
{
"message": "success", "send_id" : "example_send_id"
}
제공된 전송 ID는 /send/data_series 엔드포인트의 파라미터로 사용하여 전송별 분석을 가져올 수 있습니다.
오류
서버 응답의 상태 코드 요소는 3자리 숫자이며, 코드의 첫 번째 자리가 응답 클래스를 정의합니다.
- 2XX 클래스 상태 코드(심각하지 않음)는 요청이 성공적으로 수신, 이해, 수락되었음을 나타냅니다.
- 4XX 클래스 상태 코드(심각함)는 클라이언트 오류를 나타냅니다. 4XX 오류 코드 및 설명의 전체 목록은 심각한 오류 표를 참조하세요.
- 5XX 클래스 상태 코드(심각함)는 서버 오류를 나타냅니다. 여러 가지 원인이 있을 수 있습니다. 예를 들어 접근하려는 서버가 요청을 실행할 수 없거나, 서버가 유지보수 중이어서 요청을 실행할 수 없거나, 서버에 트래픽이 많이 몰려 있는 경우입니다. 이런 경우 지수 백오프를 사용하여 요청을 다시 시도하는 것을 권장합니다. 장애나 서비스 중단이 발생한 경우, Braze는 장애 기간 동안 실패한 REST API 호출을 재실행할 수 없습니다. 장애 기간 동안 실패한 호출은 직접 다시 시도해야 합니다.
- 502 오류는 요청이 대상 서버에 도달하기 전에 실패했음을 의미합니다.
- 503 오류는 요청이 대상 서버에 도달했지만 용량 부족, 네트워크 문제 등의 이유로 요청을 완료할 수 없음을 의미합니다.
- 504 오류는 서버가 업스트림의 다른 서버로부터 응답을 받지 못했음을 나타냅니다.
심각한 오류
요청에 심각한 오류가 발생하면 다음 상태 코드와 관련 오류 메시지가 반환됩니다.
다음 오류 코드는 모두 메시지가 전송되지 않았음을 나타냅니다.
| 오류 코드 | 설명 |
|---|---|
5XX Internal Server Error |
지수 백오프를 사용하여 요청을 다시 시도하세요. |
400 Bad Request |
잘못된 구문입니다. 유효하지 않은 JSON은 HTTP 400을 반환합니다. error 필드에는 요청 본문에 유효한 application/json을 전달해야 한다는 메시지 또는 Error while parsing request body. Please check your syntax.가 포함될 수 있습니다. 요청 본문 파싱 중 오류를 참조하세요. |
400 No Recipients |
요청에 외부 ID나 Segment ID 또는 푸시 토큰이 없습니다. |
400 Invalid Campaign ID |
제공한 Campaign ID에 해당하는 메시징 API Campaign을 찾을 수 없습니다. |
400 Bad Request (transactional campaign) |
트랜잭션 Campaign은 이 엔드포인트를 통해 트리거할 수 없습니다. 대신 /transactional/v1/campaigns/{campaign_id}/send 엔드포인트를 사용하세요. campaign_id가 트랜잭션 이메일 Campaign에 속하는 경우 /campaigns/trigger/send 및 /campaigns/trigger/schedule/create에서 반환됩니다. |
400 Message Variant Unspecified |
Campaign ID는 제공했지만 메시지 배리언트 ID를 제공하지 않았습니다. |
400 Invalid Message Variant |
유효한 Campaign ID를 제공했지만, 메시지 배리언트 ID가 해당 Campaign의 어떤 메시지와도 일치하지 않습니다. |
400 Mismatched Message Type |
하나 이상의 메시지에 대해 잘못된 메시지 유형의 메시지 배리언트를 제공했습니다. |
400 Invalid Extra Push Payload |
apple_push 또는 android_push에 extra 키를 제공했지만 사전 형식이 아닙니다. |
400 Max Input Length Exceeded |
/users/track의 경우, 단일 요청에서 허용되는 최대 객체 수를 초과하면 이 오류가 발생합니다. 제한은 사용량 제한 모델에 따라 다릅니다. 대부분의 고객은 요청당 attributes, events, purchases를 합쳐 최대 75개의 객체를 지원합니다. 레거시 사용량 제한을 사용하는 고객은 각 배열이 개별적으로 최대 75개의 객체를 지원합니다. 자세한 내용은 POST: 사용자 생성 및 업데이트를 참조하세요. |
400 The max number of external_ids and aliases per request was exceeded |
50개를 초과하는 외부 ID를 호출하여 발생합니다. |
400 The max number of ids per request was exceeded |
50개를 초과하는 외부 ID를 호출하여 발생합니다. |
400 No message to send |
메시지에 페이로드가 지정되지 않았습니다. |
400 Slideup Message Length Exceeded |
슬라이드업 메시지가 140자를 초과합니다. |
400 Apple Push Length Exceeded |
JSON 페이로드가 1,912바이트를 초과합니다. |
400 Android Push Length Exceeded |
JSON 페이로드가 4,000바이트를 초과합니다. |
400 Bad Request |
send_at 날짜/시간을 파싱할 수 없습니다. |
400 Bad Request |
요청에서 in_local_time이 true이지만 회사 시간대 기준으로 time이 이미 지났습니다. |
401 Unauthorized |
유효하지 않은 API 키입니다. 일반적인 원인은 다음과 같습니다. - Authorization 헤더 누락 또는 형식 오류. 헤더 값은 Bearer 뒤에 공백, 그다음 API 키가 와야 합니다: Authorization: Bearer YOUR-API-KEY. 흔한 실수로는 Bearer 누락, Bearer 뒤의 키 누락, 값을 따옴표로 감싸는 경우가 있습니다.- 잘못된 REST 엔드포인트. 잘못된 인스턴스로 요청을 보내고 있습니다. 예를 들어 계정이 EU 인스턴스( https://dashboard-01.braze.eu)에 있는 경우 요청은 https://rest.fra-01.braze.eu로 보내야 합니다.- 권한 부족. 각 API 키는 특정 워크스페이스와 권한 집합으로 범위가 지정됩니다. 대시보드의 설정 > API 키에서 키의 권한을 확인하세요. - 잘못된 API 키. API 키는 워크스페이스별로 다릅니다. 한 워크스페이스의 키로는 다른 워크스페이스의 요청을 인증할 수 없습니다. |
403 Forbidden |
요금제가 지원하지 않거나 계정이 비활성화되었습니다. |
403 Access Denied |
사용 중인 REST API 키에 충분한 권한이 없습니다. 일반적인 원인은 다음과 같습니다.
|
404 Not Found |
유효하지 않은 URL입니다. |
415 Unsupported Media Type |
Content-Type 요청 헤더가 누락되었거나 올바르지 않습니다. 설정 페이지에서 값이 application/json인 Content-Type을 추가하세요. |
429 Rate Limited |
사용량 제한을 초과했습니다. |
요청 본문 파싱 중 오류
요청 본문이 유효한 JSON이 아닌 경우 Braze는 HTTP 400을 반환합니다. 이는 POST, PUT, PATCH 등 JSON 본문을 받는 REST 엔드포인트에 적용됩니다.
error 필드에는 요청 본문에 유효한 application/json을 전달해야 한다는 메시지가 포함됩니다. Error while parsing request body. Please check your syntax.가 표시될 수도 있습니다.
일반적인 원인으로는 후행 쉼표, JSON 내부의 주석, 작은따옴표로 묶인 문자열, 페이로드 앞의 불필요한 여는 {, JSON으로 인코딩된 객체 대신 연결된 문자열을 보내는 경우 등이 있습니다.
다시 시도하기 전에 다음을 확인하세요.
- JSON 린터로 페이로드를 검증합니다.
Content-Type: application/json을 설정하고 UTF-8로 인코딩된 JSON을 보냅니다.- HTTP 클라이언트가 원시 문자열을 연결하는 대신 객체를 JSON으로 인코딩하는지 확인합니다.
/users/track 페이로드 크기 및 요청당 객체 제한에 대해서는 잘못된 구문 또는 파싱 오류로 400 Bad Request가 발생하는 이유는 무엇인가요?를 참조하세요.