사용량 제한
Braze API 인프라는 고객 기반 전체에서 대량의 데이터를 처리하도록 설계되었습니다. 이를 위해 워크스페이스별로 API 사용량 제한을 적용합니다.
사용량 제한은 API가 주어진 시간 동안 수신할 수 있는 요청의 수입니다. 대규모 시스템에서 발생하는 부하 기반 서비스 거부 사고의 대부분은 악의적인 공격이 아닌 소프트웨어 또는 구성 오류로 인해 의도치 않게 발생합니다. 사용량 제한은 이러한 오류로 인해 고객이 Braze API 리소스를 사용하지 못하는 상황을 방지합니다. 지정된 시간 프레임 내에 너무 많은 요청이 전송되면, 429 상태 코드와 함께 오류 응답이 표시될 수 있으며, 이는 사용량 제한에 도달했음을 나타냅니다.
API 사용량 제한은 시스템의 적절한 사용에 따라 변경될 수 있습니다. 손상이나 오용을 방지하기 위해 API 호출 시 합리적인 제한을 두는 것이 좋습니다.
요청 유형별 사용량 제한
다양한 요청 유형의 기본 API 사용량 제한은 다음을 참조하세요. 이 기본 제한은 요청 시 상향할 수 있습니다. 자세한 내용은 고객 성공 매니저에게 문의하세요.
사용량 제한이 다른 요청
사용량 제한을 공유하는 요청
다음 요청에는 시간당 250,000건의 사용량 제한이 적용되며, 이 제한은 요청 간에 공유됩니다.
/app_group/sdk_authentication/create/app_group/sdk_authentication/keys/app_group/sdk_authentication/delete/app_group/sdk_authentication/primary/campaigns/details/campaigns/list/campaigns/trigger/send(비브로드캐스트 호출에만 해당—external_user_ids또는aliases를 지정하는 호출)/campaigns/trigger/schedule/create(비브로드캐스트 호출에만 해당)/campaigns/trigger/schedule/delete/campaigns/trigger/schedule/update/canvas/data_series/canvas/data_summary/canvas/details/canvas/list/canvas/trigger/send(비브로드캐스트 호출에만 해당)/canvas/trigger/schedule/create(비브로드캐스트 호출에만 해당)/canvas/trigger/schedule/delete/canvas/trigger/schedule/update/content_blocks/create/content_blocks/info/content_blocks/list/content_blocks/update/email/blocklist/email/blacklist/email/bounce/remove/email/hard_bounces/email/spam/remove/email/status/email/unsubscribes/events/data_series/kpi/dau/data_series/kpi/mau/data_series/kpi/new_users/data_series/kpi/uninstalls/data_series/messages/live_activity/start/messages/live_activity/update/messages/send(비브로드캐스트 호출에만 해당)/messages/schedule/create/messages/schedule/delete/messages/schedule/update/messages/scheduled_broadcasts/segments/data_series/segments/details/segments/list/sends/data_series/sessions/data_series/sms/invalid_phone_numbers/sms/invalid_phone_numbers/remove/subscription/status/get/subscription/user/status/templates/email/create/templates/email/info/templates/email/list/templates/email/update/users/export/global_control_group/users/export/segment
무엇이 동일한 고유 오디언스로 간주되나요?
이 내용은 다음 엔드포인트에 적용됩니다: /messages/send, /campaigns/trigger/send, /canvas/trigger/send, /campaigns/trigger/schedule/create, /canvas/trigger/schedule/create.
이러한 엔드포인트에서는 다음 항목이 모두 일치할 때 브로드캐스트 요청이 동일한 고유 오디언스를 타겟팅하는 것으로 간주됩니다.
- 트리거되는 Campaign 또는 Canvas(지정된 경우 API 요청의
campaign_id또는canvas_id) - 타겟팅되는 오디언스(Segments 또는 필터, API Campaign의 경우 API 요청의
segment_id) - 연결된 오디언스 필터(지정된 경우 API 요청의
audience객체)
이러한 속성의 고유한 조합은 각각 별개의 오디언스로 간주되므로, 고유 오디언스별 추가 사용량 제한은 각 조합에 개별적으로 적용됩니다.
API 요청 일괄 처리
Braze API는 일괄 처리를 지원하도록 설계되었습니다. 일괄 처리를 사용하면 Braze가 단일 API 호출로 최대한 많은 데이터를 받아들일 수 있으므로 API 호출을 여러 번 할 필요가 없습니다. Braze 입장에서는 데이터를 한 번에 한 호출씩 처리하는 것보다 일괄로 처리하는 편이 더 효율적입니다. 예를 들어, 일괄 처리된 API 호출 1,000건을 처리하는 데는 개별 호출 75,000건을 처리하는 것보다 적은 리소스가 필요합니다. 시간당 75,000건 이상의 호출이 필요할 수 있는 애플리케이션이라면 일괄 처리가 매우 중요합니다.
REST API 사용량 제한 상향은 API 일괄 처리 기능을 활용하는 고객을 대상으로 필요에 따라 검토됩니다.
사용자 생성 및 업데이트 엔드포인트 요청 일괄 처리
각 /users/track 요청에는 attributes, events, purchases를 모두 합쳐 최대 75개의 오브젝트를 포함할 수 있습니다. 각 오브젝트는 한 명의 사용자를 업데이트할 수 있습니다. 하나의 고객 프로필은 여러 오브젝트로 업데이트될 수 있습니다.
레거시 사용량 제한
레거시 사용량 제한이 적용되는 고객의 경우, 각 배열(attributes, events, purchases)에 독립적으로 최대 75개의 오브젝트를 포함할 수 있어 요청당 합계 최대 225개의 오브젝트를 보낼 수 있습니다.
/users/track 사용량 제한에 대한 자세한 내용은 POST: 사용자 생성 및 업데이트를 참조하세요.
이 엔드포인트로 전송된 요청은 일반적으로 다음 순서로 처리가 시작됩니다.
- 속성
- 이벤트
- 구매
메시징 엔드포인트 요청 일괄 처리
메시징 엔드포인트에 대한 단일 요청으로 다음 중 하나에 도달할 수 있습니다.
- 각각 개별 메시지 파라미터를 가진 최대 50개의 특정
external_ids - Braze 대시보드에서 생성되고
segment_id로 지정된 모든 규모의 Segment - 요청에서 연결된 오디언스 오브젝트로 정의된, 모든 규모의 추가 오디언스 필터와 일치하는 사용자
일괄 요청 예시
다음 예시는 external_id를 사용하여 이메일과 SMS에 대해 한 번의 API 호출을 수행합니다.
curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"subscription_groups":[
{
"subscription_group_id":"subscription_group_identifier",
"subscription_state":"subscribed",
"external_ids":["example-user","[email protected]"]
},
{
"subscription_group_id":"subscription_group_identifier",
"subscription_state":"subscribed",
"external_ids":["example-user","[email protected]"]
}
]
}
사용량 제한 모니터링
표준 REST API 사용량 제한이 적용되는 모든 API 요청은 Braze로 전송될 때 응답 헤더에 다음 정보를 반환합니다.
| 헤더 이름 | 설명 |
|---|---|
X-RateLimit-Limit |
지정된 간격 동안 보낼 수 있는 최대 요청 수(사용량 제한)입니다. |
X-RateLimit-Remaining |
현재 사용량 제한 기간에 남아 있는 요청 수입니다. |
X-RateLimit-Reset |
현재 사용량 제한 기간이 재설정되는 시간(UTC 에포크 초)입니다. |
트랜잭션 이메일 엔드포인트처럼 표준 REST API 사용량 제한을 우회하는 엔드포인트는 전체 외부 API 사용량 제한에 포함되지 않으며 이러한 헤더를 반환하지 않습니다.
이 정보는 Braze 대시보드가 아닌 API 요청에 대한 응답 헤더에 의도적으로 포함됩니다. 덕분에 시스템이 API와 상호작용하는 동안 실시간으로 더 잘 대응할 수 있습니다. 예를 들어 X-RateLimit-Remaining 값이 특정 임계값 아래로 떨어지면 요청 속도를 늦출 수 있습니다. 또는 값이 0에 도달하면 X-RateLimit-Reset에 지정된 시간이 지날 때까지 요청을 일시 중지할 수 있습니다.
429 Too Many Requests 응답 문제 해결
통합이 사용량 제한을 초과하여 엔드포인트가 HTTP 429 Too Many Requests 응답을 반환하면 응답 헤더를 사용하여 재시도 시점을 결정하세요.
- 요청을 일시 중지합니다. 응답에
X-RateLimit-Retry-After가 포함되어 있으면 지정된 초만큼 기다립니다. 그렇지 않으면X-RateLimit-Reset에 있는 UTC 에포크 타임스탬프까지 기다립니다. - 더 낮은 속도로 요청을 재개합니다. 각 사용량 제한 기간 내에 보내는 요청 수를 줄여
429응답이 다시 발생할 가능성을 낮춥니다. - 지원되는 경우 여러 업데이트를 하나의 요청으로 결합합니다.
/users/track의 경우 계정의 요청 객체 한도를 따르세요. - API 사용량 대시보드를 사용하여 요청 급증과
429응답 추세를 파악합니다.
엔드포인트별 기본값은 요청 유형별 사용량 제한을 참조하세요.
HTTP 헤더는 모두 소문자로 반환됩니다. 이 동작은 모든 헤더 필드 이름을 소문자로 작성하도록 규정하는 HTTP/2 프로토콜을 따릅니다. 이는 헤더 이름이 대소문자를 구분하지 않았지만 일반적으로 다양한 대소문자 조합으로 작성되었던 HTTP/1.X와는 다릅니다.
API 한도에 대해 궁금한 점이 있으면 고객 성공 매니저에게 문의하거나 지원 티켓을 열어 주세요.
엔드포인트 간 최적 지연 시간
오류를 최소화하려면 연속적인 엔드포인트 호출 사이에 5분의 지연 시간을 두는 것을 권장합니다.
Braze API를 연속으로 호출할 때는 엔드포인트 간 최적 지연 시간을 이해하는 것이 매우 중요합니다. 엔드포인트가 다른 엔드포인트의 성공적인 처리에 의존하는 경우, 너무 빨리 호출하면 오류가 발생할 수 있습니다. 예를 들어 /user/alias/new 엔드포인트를 통해 사용자에게 별칭을 할당한 다음, 해당 별칭으로 /users/track 엔드포인트를 통해 커스텀 이벤트를 보내려면 얼마나 기다려야 할까요?
정상적인 조건에서 데이터의 최종 일관성이 확보되기까지 걸리는 시간은 10~100ms(1/10초)입니다. 하지만 일관성이 확보되기까지 더 오래 걸리는 경우도 있으므로, 오류 가능성을 최소화하려면 후속 호출 사이에 5분의 지연 시간을 두는 것을 권장합니다.
페이로드 크기 제한
Braze API 요청에는 사용량 제한과 별도로 페이로드 크기 제한이 적용됩니다. 대부분의 엔드포인트는 최대 4 MB의 요청 본문을 허용합니다. 요청이 해당 제한을 초과하면 Braze는 엔드포인트에 따라 HTTP 413 Request Entity Too Large 또는 HTTP 400 Bad Request로 요청을 거부할 수 있습니다.
/users/track/bulk 엔드포인트의 페이로드 제한은 2 MB이며, 요청 본문이 이 제한을 초과하면 HTTP 400을 반환합니다. 엔드포인트별 제한 및 오류 처리에 대해서는 사용자 데이터 엔드포인트를 참조하세요.
사용량 제한 재설정
사용량 제한은 롤링 윈도우가 아니라 매시 정각에 재설정됩니다. 예를 들어 제한이 시간당 250,000건의 요청이라면, 매시 정각에 카운터가 재설정되므로 오후 10:00부터 오후 10:59 사이에 50,000건의 요청을 보내고 오후 11:00부터 오후 11:59 사이에 다시 250,000건의 요청을 보낼 수 있습니다.