Limites de taxa
A infraestrutura da API da Braze foi projetada para lidar com grandes volumes de dados de nossa base de clientes. Para isso, aplicamos limites de taxa de API por espaço de trabalho.
Um limite de taxa é o número de solicitações que a API pode receber em um determinado período. Muitos incidentes de negação de serviço baseados em carga em grandes sistemas não são intencionais — causados por erros no software ou nas configurações — e não por ataques mal-intencionados. Os limites de taxa garantem que esses erros não privem nossos clientes dos recursos da API da Braze. Se muitas solicitações forem enviadas em um determinado período, você poderá ver respostas de erro com um código de status 429, o que indica que o limite de taxa foi atingido.
Os limites de taxa da API estão sujeitos a alterações, dependendo do uso adequado de nosso sistema. Incentivamos limites sensatos ao fazer uma chamada à API para evitar danos ou uso indevido.
Limites de frequência por tipo de requisição
Consulte a seguir os limites de frequência padrão da API para diferentes tipos de requisição. Esses limites padrão podem ser aumentados mediante solicitação. Entre em contato com o seu gerente de sucesso do cliente para saber mais.
Requisições com limites de frequência diferentes
| Tipo de requisição | Limite de frequência padrão da API |
|---|---|
/users/track |
Requisições: Os limites de frequência variam de acordo com o seu contrato. Para clientes com pontos de dados em seus preços, a Braze aplica um limite de burst de 3.000 requisições a cada três segundos. Para todos os outros clientes, os limites são configurados de acordo com os termos do seu contrato. Entre em contato com o suporte da Braze ou com o seu gerente de sucesso do cliente para perguntas sobre os seus limites. Agrupamento: Até 75 objetos no total combinados entre attributes, events e purchases por requisição de API. Clientes com limites de frequência legados podem incluir até 75 objetos por array de forma independente. Para saber mais, consulte Agrupamento de requisições de User Track.Limites para Monthly Active Users CY 24-25, Universal MAU, Web MAU e Mobile MAU: Consulte Limites do Monthly Active Users CY 24-25. |
/users/track/status |
1.500 requisições por minuto. |
/users/export/ids |
Se você fez a integração em ou após 22 de agosto de 2024: 250 requisições por minuto. Se você fez a integração antes de 22 de agosto de 2024: 2.500 requisições por minuto. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20.000 requisições por minuto, compartilhadas entre os endpoints. |
/users/external_id/rename |
1.000 requisições por minuto. |
/users/external_id/remove |
1.000 requisições por minuto. |
/events/list |
1.000 requisições por hora, compartilhadas com o endpoint /purchases/product_list. |
/purchases/product_list |
1.000 requisições por hora, compartilhadas com o endpoint /events/list. |
/campaigns/data_series |
50.000 requisições por minuto. |
/messages/send/campaigns/trigger/send/canvas/trigger/send/campaigns/trigger/schedule/create/canvas/trigger/schedule/create |
Para chamadas de broadcast (quando o direcionamento abrange Segments, filtros ou um público conectado de forma ampla), 250 requisições por minuto entre todos os públicos e 10 requisições por minuto por público único (o que for atingido primeiro). Caso contrário, ao direcionar destinatários individuais, a requisição é incluída no limite de frequência compartilhado de 250.000 requisições por hora. |
/sends/id/create |
100 requisições por dia. |
/subscription/status/set |
5.000 requisições por minuto. |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId}/preference_center/v1/list/preference_center/v1/{preferenceCenterExternalId} |
1.000 requisições por minuto. |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalId} |
10 requisições por minuto. |
/catalogs/{catalog_name}/catalogs/catalogs |
50 requisições por minuto, compartilhadas entre os endpoints. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16.000 requisições por minuto, compartilhadas entre os endpoints. |
/catalogs/{catalog_name}/items/{item_id}/catalogs/{catalog_name}/items/{item_id}/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/{item_id}/catalogs/{catalog_name}/items/{item_id} |
50 requisições por minuto, compartilhadas entre os endpoints. |
/catalogs/{catalog_name}/fields/{field_name}/catalogs/{catalog_name}/fields/catalogs/{catalog_name}/selections/{selection_name}/catalogs/{catalog_name}/selections |
50 requisições por minuto, compartilhadas entre os endpoints. |
/scim/v2/Users/{id}/scim/v2/Users?filter={[email protected]}/scim/v2/Users/{id}/scim/v2/Users/{id}}/scim/v2/Users/ |
20.000 requisições por dia, por empresa, compartilhadas entre os endpoints. |
/cdi/integrations |
50 requisições por minuto. |
/cdi/integrations/{integration_id}/sync |
20 requisições por minuto. |
/cdi/integrations/{integration_id}/job_sync_status |
100 requisições por minuto. |
/media_library/create |
100 requisições por hora. |
/media_library/replace_file |
100 requisições por hora. |
Requisições com limites de frequência compartilhados
As requisições a seguir possuem um limite de frequência de 250.000 requisições por hora, compartilhado entre elas.
/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(apenas para chamadas que não são de broadcast — aquelas que especificamexternal_user_idsoualiases)/campaigns/trigger/schedule/create(apenas para chamadas que não são de broadcast)/campaigns/trigger/schedule/delete/campaigns/trigger/schedule/update/canvas/data_series/canvas/data_summary/canvas/details/canvas/list/canvas/trigger/send(apenas para chamadas que não são de broadcast)/canvas/trigger/schedule/create(apenas para chamadas que não são de broadcast)/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(apenas para chamadas que não são de broadcast)/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
O que conta como o mesmo público único?
Isso se aplica aos seguintes endpoints: /messages/send, /campaigns/trigger/send, /canvas/trigger/send, /campaigns/trigger/schedule/create e /canvas/trigger/schedule/create.
Para esses endpoints, as requisições de broadcast são consideradas como direcionadas ao mesmo público único quando todos os itens a seguir são iguais:
- A Campaign ou Canvas sendo disparada (o
campaign_idoucanvas_idna sua requisição de API, se especificado) - O público sendo direcionado (os Segments ou filtros ou, para Campaigns de API, o
segment_idna sua requisição de API) - Os filtros de público conectado (o objeto
audiencena sua requisição de API, se especificado)
Cada combinação única desses atributos conta como um público distinto, então o limite de frequência adicional para cada público único se aplica a cada combinação de forma independente.
Agrupamento de requisições de API em lote
As APIs da Braze são desenvolvidas para suportar o envio em lote (batching). Com o agrupamento em lote, a Braze pode receber o máximo de dados possível em uma única chamada de API, de modo que você não precise fazer muitas chamadas. É mais eficiente para a Braze processar dados em lotes do que processá-los uma chamada por vez. Por exemplo, processar 1.000 chamadas de API em lote exige menos recursos do que processar 75.000 chamadas individuais. O agrupamento em lote é extremamente importante para qualquer aplicação que precise fazer mais de 75.000 chamadas por hora.
Aumentos no limite de frequência da REST API são considerados com base na necessidade dos clientes que estão utilizando os recursos de agrupamento em lote da API.
Agrupamento de requisições para o endpoint Criar e atualizar usuários
Cada requisição /users/track pode conter até 75 objetos no total, combinados entre attributes, events e purchases. Cada objeto pode atualizar um usuário. Um único perfil de usuário pode ser atualizado por múltiplos objetos.
Limites de frequência legados
Para clientes com limites de frequência legados, cada array (attributes, events e purchases) pode conter até 75 objetos de forma independente, totalizando um máximo combinado de até 225 objetos por requisição.
Para saber mais sobre os limites de frequência de /users/track, consulte POST: Criar e atualizar usuários.
As requisições feitas a esse endpoint geralmente começam a ser processadas na seguinte ordem:
- Atributos
- Eventos
- Compras
Agrupamento de requisições para endpoints de envio de mensagens
Uma única requisição para os endpoints de envio de mensagens pode alcançar qualquer um dos seguintes:
- Até 50
external_idsespecíficos, cada um com parâmetros de mensagem individuais - Um Segment de qualquer tamanho criado no dashboard da Braze, especificado pelo seu
segment_id - Usuários que correspondem a filtros de público adicionais de qualquer tamanho, definidos na requisição como um objeto de público conectado
Exemplo de requisição em lote
O exemplo a seguir usa external_id para fazer uma única chamada de API para e-mail e SMS.
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]"]
}
]
}
Monitorando seus limites de frequência
Cada requisição de API enviada à Braze retorna as seguintes informações nos cabeçalhos da resposta:
| Nome do cabeçalho | Descrição |
|---|---|
X-RateLimit-Limit |
O número máximo de requisições que você pode fazer em um intervalo especificado (seu limite de frequência). |
X-RateLimit-Remaining |
O número de requisições restantes na janela atual do limite de frequência. |
X-RateLimit-Reset |
O horário em que a janela atual do limite de frequência é redefinida, em segundos epoch UTC. |
Essas informações são intencionalmente incluídas no cabeçalho da resposta à requisição de API, e não no dashboard da Braze. Isso permite que seu sistema reaja melhor em tempo real enquanto você interage com nossa API. Por exemplo, se o valor de X-RateLimit-Remaining cair abaixo de um determinado limite, você pode querer reduzir o ritmo de envio para garantir que todos os e-mails de transação sejam entregues. Ou, se ele chegar a zero, você pode querer pausar todos os envios até que o tempo especificado em X-RateLimit-Reset expire.
Os cabeçalhos HTTP serão retornados inteiramente em caracteres minúsculos. Esse comportamento está alinhado com o protocolo HTTP/2, que exige que todos os nomes de campos de cabeçalho sejam em minúsculas. Isso difere do HTTP/1.X, em que os nomes dos cabeçalhos não diferenciavam maiúsculas de minúsculas, mas costumavam ser escritos com diversas capitalizações.
Se você tiver dúvidas sobre limites de API, entre em contato com seu gerente de sucesso do cliente ou abra um ticket de suporte.
Você pode usar o dashboard de uso de API para visualizar e comparar o tráfego de entrada em relação aos seus limites de frequência.
Intervalo ideal entre endpoints
Recomendamos que você aguarde um intervalo de 5 minutos entre chamadas consecutivas a endpoints para minimizar erros.
Entender o intervalo ideal entre endpoints é essencial ao fazer chamadas consecutivas à API da Braze. Problemas surgem quando endpoints dependem do processamento bem-sucedido de outros endpoints e, se chamados cedo demais, podem gerar erros. Por exemplo, se você está atribuindo um alias a usuários por meio do endpoint /user/alias/new e, em seguida, usando esse alias para enviar um evento personalizado pelo endpoint /users/track, quanto tempo você deve esperar?
Em condições normais, o tempo para a consistência eventual dos nossos dados ocorrer é de 10 a 100 ms (1/10 de segundo). No entanto, pode haver casos em que essa consistência leve mais tempo. Por isso, recomendamos que você aguarde um intervalo de 5 minutos entre chamadas subsequentes para minimizar a probabilidade de erro.
Limites de tamanho da carga útil
As solicitações à API da Braze estão sujeitas a limites de tamanho da carga útil, separados dos limites de frequência. A maioria dos endpoints aceita corpos de solicitação de até 4 MB. Quando uma solicitação excede o limite aplicável, a Braze pode rejeitá-la com HTTP 413 Request Entity Too Large ou HTTP 400 Bad Request, dependendo do endpoint.
O endpoint /users/track/bulk possui um limite de carga útil de 2 MB e retorna HTTP 400 quando o corpo da solicitação excede esse limite. Para limites e tratamento de erros específicos de cada endpoint, consulte Endpoints de dados de usuários.
Redefinição do limite de frequência
Os limites de frequência são redefinidos na hora cheia do relógio, e não em uma janela contínua. Por exemplo, se o limite for de 250.000 solicitações por hora, você pode fazer 50.000 solicitações entre 22h00 e 22h59 e outras 250.000 solicitações entre 23h00 e 23h59, porque o contador é redefinido no início de cada hora.