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 tabela a seguir para ver 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. Para saber mais, entre em contato com seu gerente de sucesso do cliente.
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 seu contrato. Para clientes com pontos de dados no plano de preços, a Braze aplica um limite de pico de 3.000 solicitações a cada três segundos. Para todos os outros clientes, os limites são configurados de acordo com os termos do contrato. Se tiver dúvidas sobre seus limites, entre em contato com o suporte da Braze ou com seu gerente de sucesso do cliente. Agrupamento em lote: Até 75 objetos no total, somando attributes, events e purchases, por solicitação da API. Clientes com limites de frequência legados podem incluir até 75 objetos em cada array, de forma independente. Para saber mais, consulte Agrupamento em lote de solicitações User Track.Limites para Monthly Active Users CY 24-25, Universal MAU, Web MAU e Mobile MAU: Consulte Limites de Monthly Active Users CY 24-25. |
/users/track/status |
1.500 solicitações por minuto. |
/users/export/ids |
Se o seu onboarding foi feito em 22 de agosto de 2024 ou depois: 250 solicitações por minuto. Se o seu onboarding foi feito 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 transmissão (quando você faz um direcionamento amplo para Segments, filtros ou um público conectado), 250 solicitações por minuto considerando todos os públicos e 10 solicitações por minuto por público único (o que for atingido primeiro). Caso contrário, ao direcionar para destinatários individuais, a solicitação entra 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 de transmissão—aquelas que especificamexternal_user_idsoualiases)/campaigns/trigger/schedule/create(apenas para chamadas que não são de transmissão)/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 transmissão)/canvas/trigger/schedule/create(apenas para chamadas que não são de transmissão)/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 transmissão)/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 transmissão são consideradas direcionadas ao mesmo público único quando todos os itens a seguir coincidem:
- A Campaign ou o Canvas que está sendo disparado (o
campaign_idoucanvas_idna sua solicitação da API, se especificado) - O público que está sendo direcionado (os Segments ou filtros ou, para Campaigns de API, o
segment_idna sua solicitação da API) - Os filtros de público conectado (o objeto
audiencena sua solicitação da 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.
Solicitações de API em lote
As APIs da Braze foram criadas para dar suporte ao envio em lote. Com o envio em lote, a Braze consegue receber o máximo de dados possível em uma única chamada de API, então você não precisa fazer muitas chamadas. Para a Braze, processar dados em lotes é mais eficiente do que processar uma chamada por vez. Por exemplo, lidar com 1.000 chamadas de API em lote exige menos recursos do que lidar com 75.000 chamadas individuais. O envio em lote é extremamente importante para qualquer aplicativo que possa precisar de mais de 75.000 chamadas por hora.
Aumentos no limite de frequência da REST API são avaliados conforme a necessidade de clientes que usam os recursos de envio em lote da API.
Solicitações em lote para o endpoint Criar e atualizar usuários
Cada solicitação para /users/track pode conter até 75 objetos no total, somando attributes, events e purchases. Cada objeto pode atualizar um usuário. Um único perfil de usuário pode ser atualizado por vários 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 no máximo 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 para esse endpoint geralmente começam a ser processadas nesta ordem:
- Atributos
- Eventos
- Compras
Solicitações em lote para endpoints de envio de mensagens
Uma única solicitação aos endpoints de envio de mensagens pode alcançar qualquer uma das opções a seguir:
- 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 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 ú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]"]
}
]
}
Monitoramento dos limites de frequência
Toda solicitação de API enviada à Braze que está sujeita ao limite de frequência padrão da REST API 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 solicitações que você pode fazer em um intervalo especificado (seu limite de frequência). |
X-RateLimit-Remaining |
O número de solicitações restantes na janela atual do limite de frequência. |
X-RateLimit-Reset |
O momento em que a janela atual do limite de frequência é redefinida, em segundos de época UTC. |
Endpoints que ignoram o limite de frequência padrão da REST API, como os endpoints de e-mail de transação, não contam para o seu limite geral de frequência da API externa e não retornam esses cabeçalhos.
Essas informações são incluídas intencionalmente no cabeçalho da resposta à solicitação da 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, talvez seja melhor desacelerar suas solicitações. Ou, se chegar a zero, talvez seja melhor pausar as solicitações até que o tempo especificado em X-RateLimit-Reset termine.
Solução de problemas de 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 da resposta para determinar quando tentar novamente:
- Pause as solicitações. Se a resposta incluir
X-RateLimit-Retry-After, aguarde o número de segundos especificado. Caso contrário, aguarde até o carimbo de data/hora de época UTC emX-RateLimit-Reset. - Retome as solicitações em uma taxa menor. Envie menos solicitações em cada janela do limite de frequência para reduzir a probabilidade de outra resposta
429. - Quando houver suporte, combine várias atualizações em cada solicitação. Para
/users/track, siga o limite de objetos de solicitação da sua conta. - Use o dashboard de uso da API para identificar picos de solicitações e tendências de respostas
429.
Para ver os padrões específicos de cada endpoint, consulte Limites de frequência por tipo de solicitação.
Os cabeçalhos HTTP serão retornados com todos os caracteres em minúsculas. Esse comportamento está alinhado com o protocolo HTTP/2, que exige que todos os nomes de campos de cabeçalho estejam em minúsculas. Isso é diferente do HTTP/1.X, em que os nomes dos cabeçalhos não diferenciavam maiúsculas de minúsculas, mas eram comumente escritos com várias capitalizações.
Se tiver dúvidas sobre os limites da 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 recebido com seus limites de frequência.
Postergação ideal entre endpoints
Recomendamos que você considere uma postergação de 5 minutos entre chamadas consecutivas de endpoints para minimizar erros.
Entender a postergação ideal entre endpoints é fundamental ao fazer chamadas consecutivas para a API da Braze. Surgem problemas quando os 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 aos usuários pelo nosso endpoint /user/alias/new e, em seguida, usando esse alias para enviar um evento personalizado pelo nosso endpoint /users/track, quanto tempo 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, em alguns casos essa consistência pode demorar mais. Portanto, recomendamos que você considere uma postergação de 5 minutos entre chamadas subsequentes para minimizar a probabilidade de erro.
Limites de tamanho da carga útil
As solicitações da API da Braze estão sujeitas a limites de tamanho da carga útil, que são 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 tem um limite de carga útil de 2 MB e retorna HTTP 400 quando o corpo da solicitação excede esse limite. Para saber mais sobre 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 virada de cada hora cheia, e não em uma janela móvel. 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. Isso acontece porque o contador é zerado no início de cada hora.