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 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 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 com 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 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 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/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 (direcionamento amplo a 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/		 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 seguintes requisições 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 itens a seguir coincidem:

  • A Campaign ou o Canvas sendo disparado (o campaign_id ou canvas_id na sua requisição de API, se especificado)
  • O público 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 de forma independente.

Agrupamento de solicitações de API em lote

As APIs da Braze são projetadas para oferecer suporte ao agrupamento 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, para que você não precise fazer muitas chamadas. É mais eficiente para a Braze processar dados em lotes do que processar dados uma chamada de cada vez. Por exemplo, processar 1.000 chamadas de API em lote requer menos recursos do que processar 75.000 chamadas individuais. O agrupamento em lote é extremamente importante para qualquer aplicação que possa exigir mais de 75.000 chamadas por hora.

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 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 do /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 em lote

Uma única solicitação aos 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 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 única 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 solicitaçã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 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 horário em que a janela atual do limite de frequência será redefinida, em segundos epoch UTC.

Essas informações são incluídas intencionalmente no cabeçalho da resposta à solicitaçã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, pode ser interessante reduzir a velocidade de envio para garantir que todos os e-mails de transação sejam entregues. Ou, se chegar a zero, pode ser necessário pausar todos os envios até que o tempo especificado em X-RateLimit-Reset tenha passado.

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 é crucial 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 pelo 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 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 leve mais tempo. 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 requisiçõ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 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 contínua. Por exemplo, se o limite é de 250.000 requisições por hora, você poderia fazer 50.000 requisições entre 22h00 e 22h59 e outras 250.000 requisições entre 23h00 e 23h59, porque o contador é redefinido no início de cada hora.
New Stuff!