사용자 만들기 및 업데이트

이 엔드포인트를 사용하여 커스텀 이벤트 및 구매를 기록하고 고객 프로필 속성을 업데이트하세요.

참고

/users/track에 대한 요청에서 전송되는 각 커스텀 속성은 데이터 포인트를 소비합니다. 자세한 내용은 데이터 포인트를 참조하세요.

Braze는 API를 통해 전달된 데이터를 액면 그대로 처리하며, 불필요한 데이터 포인트 로깅을 최소화하기 위해 델타(변경된 데이터)만 전달해야 합니다.

대량으로 사용자를 업데이트해야 하나요?

/users/track/bulk 엔드포인트를 사용하여 더 큰 배치를 전송하고 요청 볼륨을 줄이세요.

필수 조건

이 엔드포인트를 사용하려면 users.track 권한이 있는 API 키가 필요합니다.

서버 간 호출에 API를 사용하는 고객이 방화벽 뒤에 있는 경우 rest.iad-01.braze.com을 허용 목록에 추가해야 할 수 있습니다.

사용량 제한

이 엔드포인트의 사용량 제한은 계약에 따라 다릅니다. 요금제에 데이터 포인트가 포함된 고객의 경우, Braze는 3초당 3,000건의 요청이라는 버스트 제한을 적용합니다. 그 외 모든 고객의 경우, 계약 조건에 따라 제한이 설정됩니다. 현재 계정의 제한은 대시보드에서 설정 > API 및 식별자 > API 사용량 대시보드에서 확인할 수 있습니다.

각 /users/track 요청은 attributes, events, purchases를 합산하여 최대 75개의 오브젝트를 포함할 수 있습니다. 각 오브젝트는 한 명의 사용자를 업데이트할 수 있습니다. 단일 고객 프로필은 여러 오브젝트로 업데이트할 수 있습니다.

월간 활성 사용자 CY 24-25, Universal MAU, Web MAU 또는 Mobile MAU를 구매한 고객에게는 추가 사용량 제한이 적용됩니다. 자세한 내용은 월간 활성 사용자 CY 24-25 제한을 참조하세요.

자세한 내용은 API 사용량 제한을 참조하세요. 한도 증액이 필요하시면 고객 성공 매니저에게 문의하세요.

요청 본문

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6

{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object),
  "group_id": (optional, string)
}

요청 매개변수

중요

다음 표에 나열된 각 요청 구성요소에 대해 external_id, user_alias, braze_id, email 또는 phone 중 하나를 포함해야 합니다.

참고

Braze는 가져온 푸시 토큰을 앱과 환경에 대한 유효한 포그라운드 푸시 토큰으로 간주합니다.

iOS 토큰을 가져올 때, Braze는 해당 토큰에 대한 Apple Push Notification service(APNs) 게이트웨이(development 또는 production)를 저장하지 않습니다. Braze는 앱에 구성된 게이트웨이를 통해 이러한 토큰으로 전송합니다. 다른 환경용으로 생성된 토큰인 경우, APNs가 BadDeviceToken으로 거부하며 전송이 반송됩니다.

Braze는 나중에 SDK가 동일한 토큰을 등록하고 게이트웨이를 보고하는 경우에만 해당 토큰에 대한 게이트웨이를 저장합니다.

식별자 확인

각 요청 오브젝트에는 하나 이상의 식별자가 포함되어야 합니다. 다음 표에서는 Braze가 고객 프로필 조회에 사용할 식별자를 결정하는 방법을 설명합니다.

기본 식별자가 있는 경우 동일한 요청 오브젝트의 email 또는 phone 값은 사용자 조회를 위한 식별자가 아닌 프로필 속성으로 처리됩니다. 예를 들어, 요청에 external_id와 email이 모두 포함된 경우:

• Braze는 external_id로 고객 프로필을 조회합니다.
• email 값은 확인된 프로필의 속성으로 설정(또는 업데이트)됩니다.

중요

기존 프로필과 일치하지 않는 기본 식별자를 포함하면, 동일한 요청의 email 또는 phone이 기존 프로필과 일치하더라도 중복 프로필이 생성될 수 있습니다. 자세한 내용은 중복 고객 프로필 생성을 방지하려면 어떻게 해야 하나요?를 참조하세요.

요청 예시

이메일 주소로 고객 프로필 업데이트

/users/track 엔드포인트를 사용하여 이메일 주소로 고객 프로필을 업데이트할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "email": "[email protected]",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2022-12-06T19:20:45+01:00",
            "properties": {
                "release": {
                    "studio": "FilmStudio",
                    "year": "2022"
                },
                "cast": [
                    {
                        "name": "Actor1"
                    },
                    {
                        "name": "Actor2"
                    }
                ]
            }
        },
        {
            "user_alias": {
                "alias_name": "device123",
                "alias_label": "my_device_identifier"
            },
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2013-07-16T19:20:50+01:00"
        }
    ],
    "purchases": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "product_id": "product_name",
            "currency": "USD",
            "price": 12.12,
            "quantity": 6,
            "time": "2017-05-12T18:47:12Z",
            "properties": {
                "color": "red",
                "monogram": "ABC",
                "checkout_duration": 180,
                "size": "Large",
                "brand": "Backpack Locker"
            }
        }
    ]
}'

전화번호로 고객 프로필 업데이트

/users/track 엔드포인트를 사용하여 전화번호로 고객 프로필을 업데이트할 수 있습니다. 이 엔드포인트는 유효한 전화번호를 포함하는 경우에만 작동합니다.

중요

요청에 email과 phone을 모두 포함하면 Braze는 이메일을 식별자로 사용합니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "phone": "+15043277269",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
}'

구독 그룹 설정

이 예시에서는 사용자를 만들고 사용자 속성 오브젝트 내에서 구독 그룹을 설정하는 방법을 보여줍니다.

이 엔드포인트로 구독 상태를 업데이트하면 external_id로 지정한 사용자(예: User1)가 업데이트되고 해당 사용자(User1)와 동일한 이메일을 사용하는 모든 사용자의 구독 상태가 업데이트됩니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
  {
    "external_id": "user_identifier",
    "email": "[email protected]",
    "email_subscribe": "subscribed",
    "subscription_groups": [{
      "subscription_group_id": "subscription_group_identifier_1",
      "subscription_state": "unsubscribed"
      },
      {
        "subscription_group_id": "subscription_group_identifier_2",
        "subscription_state": "subscribed"
        },
        {
          "subscription_group_id": "subscription_group_identifier_3",
          "subscription_state": "subscribed",
          "use_double_opt_in_logic": true
        }
      ]
    }
  ]
}'

참고

SMS 구독 그룹의 경우, 그룹의 subscription_state를 subscribed로 설정할 때 해당 구독 그룹 오브젝트 내에 선택적 use_double_opt_in_logic 매개변수를 true로 설정하여 사용자를 SMS 이중 옵트인 워크플로에 진입시킬 수 있습니다. subscription_state가 subscribed일 때 이 매개변수를 생략하거나 false로 설정하면 사용자는 이중 옵트인 워크플로를 거치지 않고 바로 구독됩니다. 이 매개변수는 subscription_state가 unsubscribed와 같은 다른 값으로 설정된 경우에는 적용되지 않습니다.

별칭 전용 사용자 만들기 요청 예시

/users/track 엔드포인트를 사용하여 요청 본문에서 _update_existing_only 키를 false 값으로 설정하면 별칭 전용 사용자를 만들 수 있습니다. 이 값을 생략하면 Braze는 별칭 전용 고객 프로필을 생성하지 않습니다. 별칭 전용 사용자를 사용하면 해당 별칭을 가진 프로필이 하나만 존재하게 됩니다. 이는 통합을 구축할 때 특히 유용하며, Braze가 중복된 고객 프로필을 생성하는 것을 방지할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "_update_existing_only": false,
            "user_alias": {
                "alias_name": "example_name",
                "alias_label": "example_label"
            },
            "email": "[email protected]"
        }
    ],
}'

상태 추적을 위한 그룹 ID가 포함된 요청 예시

이 예시에서는 사용자의 로열티 등급을 업데이트하고 group_id를 포함하여 Braze가 요청 처리를 완료한 시점을 확인할 수 있습니다. 상태를 확인하려면 동일한 group_id로 /users/track/status 엔드포인트를 호출하세요. 자세한 내용은 요청 처리 상태 추적을 참조하세요.

1
2
3
4
5
6
7
8
9
10
11
12

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "group_id": "loyalty_backfill_2026-09-23",
    "attributes": [
        {
            "external_id": "user_identifier",
            "loyalty_tier": "gold"
        }
    ]
}'

응답

앞서 언급한 API 요청을 사용할 때 성공 메시지, 치명적이지 않은 오류가 있는 성공 메시지, 심각한 오류가 있는 메시지 등 세 가지 일반적인 응답 중 하나를 받게 됩니다.

성공 메시지

성공 메시지는 다음과 같은 응답을 반환합니다:

1
2
3
4
5
6

{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external_ids with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing,
}

치명적이지 않은 오류가 있는 성공 메시지

메시지는 성공했지만 긴 이벤트 목록 중 하나의 잘못된 이벤트 오브젝트와 같이 치명적이지 않은 오류가 있는 경우 다음과 같은 응답을 받게 됩니다:

1
2
3
4
5
6
7
8

{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

성공 메시지의 경우 Braze는 errors 배열의 오류에 영향을 받지 않는 모든 데이터를 계속 처리합니다.

심각한 오류가 있는 메시지

메시지에 심각한 오류가 있는 경우 다음과 같은 응답을 받게 됩니다:

1
2
3
4
5
6
7
8

{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

심각한 오류 응답 코드

요청에 심각한 오류가 발생할 경우 Braze가 반환하는 상태 코드 및 관련 오류 메시지는 심각한 오류 및 응답을 참조하세요.

“provided external_id is blacklisted and disallowed”라는 오류가 표시되는 경우 요청에 “더미 사용자”가 포함된 것일 수 있습니다. 자세한 내용은 스팸 차단을 참조하세요.

엔드포인트별 오류

다음 오류는 /users/track 엔드포인트에 한정된 것이며 응답의 errors 배열에 반환됩니다. 이를 사용하여 요청의 개별 오브젝트 관련 문제를 해결하세요.

요청 처리 상태 추적

중요

요청 처리 상태는 베타 버전입니다. 베타에 참여하려면 Braze 계정 매니저에게 문의하세요.

Braze는 /users/track 요청을 비동기적으로 처리합니다. 성공 응답은 Braze가 요청을 수신하고 처리 대기줄에 넣었음을 의미하지만, 데이터가 아직 고객 프로필에 반영되지 않았을 수 있습니다. 처리가 완료되는 시점을 확인하려면 요청에 group_id를 추가하고 /users/track/status 엔드포인트로 그룹 상태를 확인하세요.

요청 처리 상태를 사용하여 다음을 수행할 수 있습니다:

• 속성 또는 구독 업데이트가 프로필에 반영된 후에 이를 의존하는 Canvas 또는 Campaign을 트리거하도록 확인합니다.
• 백필 또는 가져오기가 완료된 후에 영향을 받는 사용자에게 메시지를 발송합니다.
• 동의 변경과 같은 우선순위가 높은 업데이트가 처리 완료되었음을 기록합니다.

작동 방식

1. 관련 요청 집합에 대한 group_id를 선택합니다. 예를 들어, 백필의 모든 요청에 하나의 group_id를 사용하거나 확인하려는 단일 요청에 고유한 group_id를 사용합니다.
2. 각 /users/track 요청 본문의 최상위 레벨에 group_id를 포함합니다. Braze는 수락된 각 요청을 그룹에 카운트합니다.
3. 해당 group_id로 /users/track/status 엔드포인트를 호출합니다. 그룹의 status가 completed이면 Braze가 그룹의 모든 요청 처리를 완료한 것입니다.

그룹이 completed된 후 동일한 group_id로 다른 요청을 보내면, Braze가 새 요청 처리를 완료할 때까지 그룹 상태가 processing으로 돌아갑니다.

Braze는 각 그룹의 상태를 전체적으로 추적합니다. 그룹은 Braze가 일부 오브젝트를 거부한 요청을 포함하여 그룹의 모든 요청 처리를 완료하면 completed됩니다. Braze는 거부된 오브젝트를 각 /users/track 응답의 errors 배열에 나열합니다.

상태 추적은 /users/track 엔드포인트에서만 사용할 수 있습니다. Braze는 /users/track/bulk 엔드포인트 또는 /users/track/sync 엔드포인트에 대한 요청 상태를 추적하지 않습니다.

그룹 ID 요구 사항

group_id는 1~128자여야 하며 문자, 숫자, 마침표(.), 밑줄(_), 물결표(~), 하이픈(-)만 포함할 수 있습니다.

그룹 ID는 워크스페이스 범위입니다. 두 워크스페이스에서 동일한 group_id는 두 개의 별도 그룹을 참조합니다.

추적하려는 각 요청 집합에 새로운 group_id를 사용하세요. group_id를 재사용하면 기존 그룹에 요청이 추가되며 보존 기간이 연장되지 않습니다.

제한 및 보존

상태 추적 오류

워크스페이스가 최대 활성 그룹 수에 도달한 경우와 같이 일부 상황에서는 Braze가 요청 상태를 추적할 수 없습니다. 이 경우 /users/track 응답은 여전히 성공하며 Braze는 요청의 속성, 이벤트 및 구매를 계속 처리합니다. 응답에는 Braze가 요청을 추적하지 않는 이유를 설명하는 항목이 errors 배열에 포함됩니다:

1
2
3
4
5
6
7
8

{
  "message": "success",
  "errors": [
    {
      "type": "request_status_group_full"
    }
  ]
}

자주 묻는 질문

중요

법적으로 요구되는 트랜잭션 이메일은 전달되지 않을 가능성이 높으므로 SMS 게이트웨이로 보내지 마세요.

전화번호와 제공업체의 게이트웨이 도메인(MM3라고 함)을 사용하여 보내는 이메일은 SMS(문자) 메시지로 수신될 수 있지만, 일부 이메일 제공업체는 이 동작을 지원하지 않습니다. 예를 들어, T-Mobile 전화번호(예: “[email protected]”)로 이메일을 보내면 T-Mobile 네트워크에서 해당 전화번호를 소유한 사람에게 SMS 메시지가 전송됩니다.

이러한 이메일이 SMS 게이트웨이로 전달되지 않더라도 이메일 요금 청구에 포함된다는 점에 유의하세요. 지원되지 않는 게이트웨이로 이메일을 보내지 않으려면 지원되지 않는 게이트웨이 도메인 이름 목록을 검토하세요.

동일한 이메일 주소를 가진 프로필이 여러 개 발견되면 어떻게 되나요?

external_id가 존재하는 경우, Braze는 외부 ID가 있는 가장 최근에 업데이트된 프로필을 우선적으로 업데이트합니다. external_id가 존재하지 않는 경우 Braze는 가장 최근에 업데이트된 프로필을 우선적으로 업데이트합니다.

이메일 주소가 포함된 프로필이 없는 경우 어떻게 되나요?

Braze는 이메일 주소로 고객 프로필 업데이트 요청 예시에 나와 있는 것처럼 프로필과 이메일 전용 사용자를 생성하고 이메일 필드를 [email protected]으로 설정합니다. Braze는 별칭을 만들지 않습니다.

기존 사용자 데이터를 가져오기 위해 /users/track을 어떻게 사용하나요?

아직 모바일 앱을 사용하지 않은 사용자를 위해 Braze API를 통해 데이터를 제출하여 고객 프로필을 생성할 수 있습니다. 이후 사용자가 애플리케이션을 사용하면 SDK를 통해 식별된 후의 모든 정보가 API 호출로 생성한 기존 고객 프로필과 병합됩니다. 식별 전에 SDK에 의해 익명으로 기록된 모든 사용자 행동은 기존 API 생성 고객 프로필과 병합되면 손실됩니다.

세분화 툴에는 앱 참여 여부와 관계없이 이러한 사용자가 포함됩니다. 사용자 API를 사용하여 업로드한 사용자 중 아직 앱에 참여하지 않은 사용자를 제외하려면 Session Count > 0 필터를 추가하세요.

중복 고객 프로필 생성을 방지하려면 어떻게 해야 하나요?

중복 프로필은 요청에 기존 프로필과 일치하지 않는 기본 식별자(예: external_id)가 포함되어 있고, 동시에 기존 프로필과 일치하는 email 또는 phone 값이 포함된 경우 발생할 수 있습니다. 기본 식별자가 사용자 조회에 사용되므로, Braze는 인식되지 않는 external_id에 대해 기존 이메일 전용 또는 전화번호 전용 프로필을 업데이트하는 대신 새 프로필을 생성합니다.

중복을 방지하려면:

• 이메일 전용 또는 전화번호 전용 프로필에서 식별된 프로필로 사용자를 전환할 때, /users/track에 둘 다 보내는 대신 /users/identify 엔드포인트를 사용하여 기존 프로필에 external_id를 할당하세요.
• 중복이 이미 존재하는 경우 /users/merge 엔드포인트를 사용하여 병합하세요.

/users/track에서는 중복 이벤트를 어떻게 처리하나요?

이벤트 배열의 각 이벤트 오브젝트는 지정된 시간에 사용자가 수행한 커스텀 이벤트의 단일 발생을 나타냅니다. 즉, Braze에 수집된 각 이벤트에는 고유한 이벤트 ID가 있으므로 “중복” 이벤트는 별도의 고유한 이벤트로 취급됩니다.

/users/track에서는 잘못된 중첩 커스텀 속성을 어떻게 처리하나요?

중첩 커스텀 속성에 유효하지 않은 값(예: 잘못된 시간 형식 또는 null 값)이 포함된 경우 Braze는 요청의 모든 중첩 커스텀 속성 업데이트를 처리에서 삭제합니다. 이는 해당 특정 속성 내의 모든 중첩 구조에 적용됩니다. 성공적인 처리를 위해 전송하기 전에 중첩 커스텀 속성 내의 모든 값이 유효한지 확인하세요.

/users/track에 대한 요청이 순서대로 처리되는 것이 보장되나요?

/users/track에 여러 개의 별도 API 호출을 빠르게 연속으로 수행하는 경우, Braze는 요청이 전송되거나 수신된 정확한 순서대로 처리되는 것을 보장할 수 없습니다. 이는 Braze가 속도와 유연성을 극대화하기 위해 비동기 처리를 사용하기 때문입니다.

예를 들어, 동일한 사용자에 대해 몇 초 이내에 여러 업데이트 요청을 보내는 경우(일부는 null 속성 값, 일부는 유효한 값), null 값을 포함하는 요청이 유효한 값을 포함하는 요청보다 나중에 처리될 수 있습니다(먼저 전송되었더라도). 이로 인해 속성 값이 되돌아가거나 가장 최근에 전송한 업데이트가 반영되지 않는 것처럼 보일 수 있습니다.

사용자 데이터를 업데이트할 때 경합 조건을 방지하려면:

• 단일 요청에 업데이트를 일괄 처리하세요: 별도의 연속 호출을 하는 대신 하나의 API 호출에 사용자에 대한 모든 속성 업데이트를 포함하세요.
• 요청 사이에 지연을 추가하세요: 동일한 사용자에 대해 별도의 호출을 해야 하는 경우, 다음 요청을 보내기 전에 첫 번째 요청이 처리를 완료할 수 있도록 요청 사이에 몇 초의 지연을 추가하세요.
• 동일한 필드에 대한 중복 업데이트를 피하세요: 두 요청이 동일한 속성을 다른 값으로 업데이트하는 경우, 해당 업데이트를 하나의 요청으로 보내거나 순서가 뒤바뀔 가능성을 줄이기 위해 지연을 두고 분리하세요.
• 다음 요청 전에 처리 완료를 확인하세요(베타): 첫 번째 요청에 group_id를 포함하고, /users/track/status 엔드포인트가 completed를 반환할 때까지 기다린 후 종속 요청을 보내세요. 자세한 내용은 요청 처리 상태 추적을 참조하세요.

경합 조건 및 모범 사례에 대한 자세한 내용은 경합 조건을 참조하세요.

Braze가 요청 처리를 완료한 시점을 어떻게 알 수 있나요?

/users/track 요청에 group_id를 포함한 다음, 해당 group_id로 /users/track/status 엔드포인트를 호출하세요. 그룹의 status가 completed이면 Braze가 그룹의 모든 요청 처리를 완료한 것입니다. 이 기능은 베타 버전입니다. 자세한 내용은 요청 처리 상태 추적을 참조하세요.

그룹 상태를 얼마나 자주 확인해야 하나요?

/users/track/status 엔드포인트를 몇 초 간격과 같은 정기적인 주기로 폴링하고, 그룹의 status가 completed이면 중지하세요. 엔드포인트의 사용량 제한인 워크스페이스당 분당 1,500건 이내로 폴링하세요.

그룹이 아직 처리 중인 이유는 무엇인가요?

그룹은 Braze가 그룹의 모든 수락된 요청 처리를 완료할 때까지 processing 상태를 유지합니다. 처리 중 요청이 실패하면 Braze가 재시도하며, 재시도가 성공할 때까지 그룹은 processing 상태를 유지합니다. 그룹이 completed된 후 요청을 추가하면 상태가 processing으로 돌아갑니다. 드문 경우지만 그룹은 보존 기간이 끝날 때까지 processing 상태를 유지할 수 있습니다. 그룹이 일반적인 처리 시간보다 훨씬 오래 processing 상태를 유지하는 경우 Braze 고객지원에 문의하세요.

/users/track/status가 빈 results 배열을 반환하는 이유는 무엇인가요?

results 배열은 Braze가 워크스페이스에서 그룹을 찾지 못한 경우 비어 있습니다. 이는 그룹의 24시간 보존 기간이 종료되었거나, group_id가 요청의 값과 일치하지 않거나, 다른 워크스페이스로 요청을 보낸 경우 발생합니다. 또한 Braze가 해당 group_id에 대한 요청을 추적하지 않은 경우에도 발생합니다. 각 /users/track 응답에서 상태 추적 오류를 확인하세요.

/users/track 응답이 예상보다 느린 이유는 무엇인가요?

성공적인 /users/track 호출은 일반적으로 빠르게 수락되지만, Braze는 속성, 이벤트 및 구매 업데이트를 비동기적으로 처리합니다. 페이로드가 크거나 REST 엔드포인트로의 네트워크 라우팅이 느린 경우 체감 지연 시간이 증가할 수 있습니다. 사용자별 동기 확인 또는 호출 간 더 엄격한 순서가 필요한 경우 /users/track/sync(제한된 베타)를 참조하세요.

/users/track에서 429 Too Many Requests가 반환되는 이유는 무엇인가요?

요청 볼륨이 사용량 제한을 초과하면 /users/track은 HTTP 429 Too Many Requests 응답을 반환합니다. 요청 전송을 재개하려면:

1. X-RateLimit-Retry-After 응답 헤더에 지정된 시간(초)만큼 요청을 일시 중지합니다.
2. 다시 429 응답을 받을 가능성을 줄이기 위해 더 낮은 속도로 요청을 재개합니다.
3. 가능한 경우 업데이트를 결합하고 계정의 요청 오브젝트 제한을 따릅니다.
4. API 사용량 대시보드를 사용하여 요청 급증 및 429 응답 추세를 파악합니다. 워크스페이스 기본값 및 기타 엔드포인트 제한에 대해서는 API 사용량 제한을 참조하세요.

지원되는 계약의 429가 아닌 응답의 경우, 월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 및 모바일 MAU에 대한 사용량 제한 헤더에 설명된 X-RateLimit-* 응답 헤더를 사용하여 현재 기간의 남은 요청 수를 확인하세요.

400 Bad Request와 함께 구문 또는 구문 분석 오류가 발생하는 이유는 무엇인가요?

구문 또는 구문 분석 오류가 포함된 HTTP 400은 일반적으로 요청 본문이 유효한 JSON이 아님을 의미합니다. 일반적인 원인으로는 후행 쉼표, JSON 내부의 주석, 작은따옴표로 묶인 문자열, 페이로드 앞의 추가 여는 {, 또는 Content-Type 헤더가 application/json인 상태에서 JSON이 아닌 본문을 전송하는 경우가 있습니다. 전송하기 전에 JSON 린터로 페이로드를 검증하고, HTTP 클라이언트가 오브젝트를 JSON으로 인코딩하는지(원시 문자열을 연결하는 것이 아닌지) 확인하고, 본문이 UTF-8로 인코딩되어 있는지 확인하세요. 기타 400 응답(예: 페이로드 크기 및 요청당 오브젝트 제한)에 대해서는 심각한 오류 및 응답 및 이 페이지의 엔드포인트별 오류 표를 참조하세요.

월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 및 모바일 MAU

새 요금제를 사용하는 고객의 경우 회사 수준에서 사용량 제한이 적용됩니다. 고객은 워크스페이스별 시간당 사용량 제한을 설정할 수 있지만 버스트 제한은 여전히 모든 워크스페이스 간에 공유됩니다.

월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 또는 모바일 MAU를 구매한 고객의 경우 Braze는 /users/track 엔드포인트에서 다양한 사용량 제한을 관리합니다:

• 시간당 사용량 제한은 계정의 예상 데이터 수집 활동에 따라 설정되며, 이는 구매한 월간 활성 사용자 수, 업종, 계절성 또는 기타 요인에 따라 달라질 수 있습니다.
• 시간당 제한 외에도 Braze는 3초마다 전송할 수 있는 요청 수에 버스트 제한을 적용합니다.
• 각 요청은 속성, 이벤트 또는 구매 오브젝트에 걸쳐 최대 75개의 업데이트를 일괄 처리할 수 있습니다.

예상 수집량에 따른 현재 제한은 대시보드의 설정 > API 및 식별자 > API 사용량 대시보드에서 확인할 수 있습니다. 시스템 안정성을 보호하거나 계정의 데이터 처리량 증가를 허용하기 위해 사용량 제한을 수정할 수 있습니다. 시간당 또는 초당 요청 제한 및 비즈니스 요구 사항에 대한 질문이나 우려 사항이 있는 경우 Braze 고객지원 또는 고객 성공 매니저에게 문의하세요.

월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 및 모바일 MAU에 대한 사용량 제한 헤더

사용량 제한이 적용되지 않은 모든 응답(예: 429가 아닌 응답)에는 클라이언트에 시간당 사용량 제한 기간의 상태를 나타내는 다음 HTTP 응답 헤더가 포함됩니다. 이 헤더를 사용하여 요청 비율을 관리하세요:

HTTP 429 오류가 발생하면 RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset 헤더는 반환되지 않습니다. 오류가 발생하면 해당 헤더는 요청을 다시 시작할 수 있는 시간(초)을 나타내는 정수를 반환하는 X-RateLimit-Retry-After 헤더로 대체됩니다.