Skip to content

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.

Limites de frequência por tipo de requisição

Consulte as informações a seguir para conhecer 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 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 dependendo do 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 seu gerente de sucesso do cliente para perguntas sobre seus limites.

Lotes: 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 independentemente. Para saber mais, consulte Requisições de User Track em lote.

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/export/ids Se você foi integrado em ou após 22 de agosto de 2024: 250 requisições por minuto.

Se você foi integrado 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 é amplo, para Segments, filtros ou um público conectado), 250 requisições por minuto em 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/		 5.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.

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 seguintes critérios correspondem:

  • A Campaign ou o Canvas que está sendo disparado (o campaign_id ou canvas_id na sua requisição de API, se especificado)
  • O público que está sendo direcionado (os Segments ou filtros, ou para Campaigns de API, o segment_id na sua requisição de API)
  • Os filtros de público conectado (o objeto audience na 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 independentemente.

Agrupamento de solicitações de API em lotes

As APIs da Braze são criadas para oferecer suporte a 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, de modo que você não precise fazer muitas chamadas. É 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.

Agrupamento de solicitações 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 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, 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 nesta ordem:

  1. Atributos
  2. Eventos
  3. Compras

Agrupamento de solicitações de 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_ids especí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 chamada de API para e-mail e SMS.

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/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 para a 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 especificado (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 desacelerar o 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 horário especificado em X-RateLimit-Reset seja atingido.

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.

Intervalo ideal entre endpoints

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ê estiver atribuindo um alias a usuários por meio do endpoint /user/alias/new e depois usando esse alias para enviar um evento personalizado por meio do 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 demore mais para ocorrer. Por isso, recomendamos que você permita 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 tem um limite de carga útil de 2 MB e retorna HTTP 400 quando o corpo da solicitaçã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 contínua. Por exemplo, se o limite for de 250.000 solicitações por hora, você poderá 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.
New Stuff!