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 solicitação
Consulte a seguir os limites de frequência padrão da API para diferentes tipos de solicitação. Esses limites padrão podem ser aumentados mediante solicitação. Entre em contato com seu gerente de sucesso do cliente para saber mais.
Solicitações com limites de frequência diferentes
| Tipo de solicitação | Limite de frequência padrão da API |
|---|---|
/users/track |
Solicitações: Os limites de frequência variam de acordo com o seu contrato. Para clientes com pontos de dados em seus planos de preços, a Braze aplica um limite de burst de 3.000 solicitações a cada três segundos. Para todos os outros clientes, os limites são configurados conforme os termos do seu contrato. Entre em contato com o suporte da Braze ou seu gerente de sucesso do cliente para dúvidas sobre seus limites. Agrupamento: Até 75 objetos no total combinados entre attributes, events e purchases por solicitaçã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 solicitações 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 solicitações por minuto. |
/users/export/ids |
Se você foi integrado em ou após 22 de agosto de 2024: 250 solicitações por minuto. Se você foi integrado antes de 22 de agosto de 2024: 2.500 solicitações por minuto. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20.000 solicitações por minuto, compartilhadas entre os endpoints. |
/users/external_id/rename |
1.000 solicitações por minuto. |
/users/external_id/remove |
1.000 solicitações por minuto. |
/events/list |
1.000 solicitações por hora, compartilhadas com o endpoint /purchases/product_list. |
/purchases/product_list |
1.000 solicitações por hora, compartilhadas com o endpoint /events/list. |
/campaigns/data_series |
50.000 solicitaçõ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 é amplo para Segments, filtros ou um público conectado), 250 solicitações por minuto entre todos os públicos e 10 solicitações por minuto por público único (o que for atingido primeiro). Caso contrário, ao direcionar destinatários individuais, a solicitação é incluída no limite de frequência compartilhado de 250.000 solicitações por hora. |
/sends/id/create |
100 solicitações por dia. |
/subscription/status/set |
5.000 solicitações por minuto. |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId}/preference_center/v1/list/preference_center/v1/{preferenceCenterExternalId} |
1.000 solicitações por minuto. |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalId} |
10 solicitações por minuto. |
/catalogs/{catalog_name}/catalogs/catalogs |
50 solicitações por minuto, compartilhadas entre os endpoints. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16.000 solicitaçõ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 solicitaçõ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 solicitaçõ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 solicitações por dia, por empresa, compartilhadas entre os endpoints. |
/cdi/integrations |
50 solicitações por minuto. |
/cdi/integrations/{integration_id}/sync |
20 solicitações por minuto. |
/cdi/integrations/{integration_id}/job_sync_status |
100 solicitações por minuto. |
/media_library/create |
100 solicitações por hora. |
/media_library/replace_file |
100 solicitações por hora. |
Solicitações com limites de frequência compartilhados
As solicitações a seguir têm um limite de frequência de 250.000 solicitaçõ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 broadcast — aquelas que especificamexternal_user_idsoualiases)/campaigns/trigger/schedule/create(apenas para chamadas que não são 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 broadcast)/canvas/trigger/schedule/create(apenas para chamadas que não são 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 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 solicitações de broadcast são consideradas como direcionadas ao mesmo público único quando todos os seguintes critérios coincidem:
- A Campaign ou Canvas sendo disparada (o
campaign_idoucanvas_idna sua solicitação de API, se especificado) - O público sendo direcionado (os Segments ou filtros, ou para Campaigns de API, o
segment_idna sua solicitação de API) - Os filtros de público conectado (o objeto
audiencena sua solicitação de API, se especificado)
Cada combinação única desses atributos conta como um público distinto. Portanto, o limite de frequência adicional para cada público único se aplica a cada combinação de forma independente.
Agrupamento de solicitações de API em lotes
As APIs da Braze são projetadas para suportar agrupamento em lotes. Com o agrupamento em lotes, a Braze pode receber o máximo de dados possível em uma única chamada de API, para que você não precise fazer muitas chamadas de API. É mais eficiente para a Braze processar dados em lotes do que processar dados uma chamada por vez. Por exemplo, lidar com 1.000 chamadas de API em lote requer menos recursos do que lidar com 75.000 chamadas individuais. O agrupamento em lotes é extremamente importante para qualquer aplicação que possa exigir mais de 75.000 chamadas por hora.
Aumentos no limite de frequência da REST API são considerados com base na necessidade para clientes que estão fazendo uso dos recursos de agrupamento em lotes da API.
Agrupamento de solicitações em lote para o endpoint Criar e atualizar usuários
Cada solicitaçã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 independentemente, para um máximo combinado de até 225 objetos por solicitação.
Para saber mais sobre os limites de frequência de /users/track, consulte POST: Criar e atualizar usuários.
As solicitações feitas a esse endpoint geralmente começam a ser processadas na seguinte ordem:
- Atributos
- Eventos
- Compras
Agrupamento em lote de solicitações para endpoints de envio de mensagens
Uma única solicitaçã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 correspondam a filtros de público adicionais de qualquer tamanho, definidos na solicitação como um objeto de público conectado
Exemplo de solicitação em lote
O exemplo a seguir usa external_id para fazer uma 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 de 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 específico (seu limite de frequência). |
X-RateLimit-Remaining |
O número de requisições restantes na janela atual de limite de frequência. |
X-RateLimit-Reset |
O horário em que a janela atual de limite de frequência é redefinida, em segundos epoch UTC. |
Essas informações são incluídas intencionalmente 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 a velocidade de envio para garantir que todos os e-mails de transação sejam enviados. Ou, se ele chegar a zero, você pode querer pausar todos os envios até que o tempo especificado em X-RateLimit-Reset tenha decorrido.
Solução de problemas com respostas 429 Too Many Requests
Se um endpoint retornar uma resposta HTTP 429 Too Many Requests porque sua integração excedeu um limite de frequência, use os cabeçalhos de resposta para determinar quando tentar novamente:
- Pause as requisições. Se a resposta incluir
X-RateLimit-Retry-After, aguarde o número de segundos especificado. Caso contrário, aguarde até o timestamp epoch UTC emX-RateLimit-Reset. - Retome as requisições a uma taxa menor. Envie menos requisições dentro de cada janela de limite de frequência para reduzir a probabilidade de outra resposta
429. - Quando suportado, combine múltiplas atualizações em cada requisição. Para
/users/track, siga o limite de objetos de requisição da sua conta. - Use o dashboard de uso da API para identificar picos de requisições e tendências de respostas
429.
Para os padrões específicos de cada endpoint, consulte Limites de frequência por tipo de requisição.
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, onde os nomes de cabeçalho não diferenciavam maiúsculas de minúsculas, mas eram comumente escritos em várias 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 da API para visualizar e comparar o tráfego de entrada com seus limites de frequência.
Atraso ideal entre endpoints
Recomendamos que você permita um atraso de 5 minutos entre chamadas consecutivas a endpoints para minimizar erros.
Compreender o atraso 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 nosso endpoint /user/alias/new e, em seguida, usando esse alias para enviar um evento personalizado por meio do nosso endpoint /users/track, quanto tempo você deve esperar?
Em condições normais, o tempo para que a consistência eventual dos nossos dados ocorra é de 10 a 100 ms (1/10 de segundo). No entanto, pode haver casos em que essa consistência demora mais, por isso recomendamos que você permita um atraso de 5 minutos entre chamadas subsequentes para minimizar a probabilidade de erro.
Limites de tamanho da carga útil
As requisições da 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 requisição de até 4 MB. Quando uma requisiçã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 tem um limite de carga útil de 2 MB e retorna HTTP 400 quando o corpo da requisição excede esse limite. Para limites específicos de cada endpoint e tratamento de erros, 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, não em uma janela deslizante. Por exemplo, se o limite for de 250.000 requisições por hora, você poderia fazer 50.000 requisições entre 22:00 e 22:59 e outras 250.000 requisições entre 23:00 e 23:59, porque o contador é redefinido no início de cada hora.