Ir para o conteúdo

Limites de frequência

A infraestrutura da API da Braze foi projetada para lidar com grandes volumes de dados de toda a nossa base de clientes. Por isso, aplicamos limites de frequência da API por espaço de trabalho.

Um limite de frequência é o número de solicitações que a API pode receber em um determinado período. Em sistemas grandes, muitos incidentes de negação de serviço causados por carga não são intencionais. Eles costumam vir de erros de software ou de configuração, e não de ataques mal-intencionados. Os limites de frequência garantem que esses erros não privem nossos clientes dos recursos da API da Braze. Se forem enviadas muitas solicitações em um determinado período, você poderá ver respostas de erro com o código de status 429, o que indica que o limite de frequência foi atingido.

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

Confira 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. 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. Em caso de dúvidas sobre seus limites, entre em contato com o suporte da Braze ou com seu gerente de sucesso do cliente.

Envio 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 por array de forma independente. Para saber mais, consulte Envio em lote de solicitações de 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 você fez o onboarding em 22 de agosto de 2024 ou depois: 250 solicitações por minuto.

Se você fez o onboarding 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 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 é contabilizada 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.

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 sendo disparado (o campaign_id ou canvas_id na sua solicitação da API, se especificado)
  • O público direcionado (os Segments ou filtros ou, no caso de Campaigns de API, o segment_id na sua solicitação da API)
  • Os filtros de público conectado (o objeto audience na 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 por 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 possível de dados em uma única chamada de API, então você não precisa fazer muitas chamadas. Para a Braze, é mais eficiente processar dados em lotes do que processar uma chamada de cada 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 aplicação que possa precisar de mais de 75.000 chamadas por hora.

Solicitações em lote para o endpoint de criação e atualização de 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:

  1. Atributos
  2. Eventos
  3. Compras

Solicitações em lote para endpoints de envio de mensagens

Uma única solicitação para os endpoints de envio de mensagens pode alcançar qualquer uma das opções a seguir:

  • 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 ú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 seus 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 da época UTC.

Os 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 de frequência geral 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 de API, e não no dashboard da Braze. Assim, seu sistema consegue reagir melhor em tempo real enquanto interage com nossa API. Por exemplo, se o valor de X-RateLimit-Remaining cair abaixo de um determinado limite, talvez seja interessante diminuir o ritmo das suas solicitações. Ou, se ele chegar a zero, talvez seja interessante 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:

  1. 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 timestamp da época UTC indicado em X-RateLimit-Reset.
  2. 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 receber outra resposta 429.
  3. 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.
  4. Use o dashboard de uso da API para identificar picos de solicitações e tendências de respostas 429.

Para saber os padrões específicos de cada endpoint, consulte Limites de frequência por tipo de solicitação.

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.

Postergação ideal entre endpoints

Entender a postergação ideal entre endpoints é fundamental ao fazer chamadas consecutivas à API da Braze. Problemas surgem quando endpoints dependem do processamento bem-sucedido de outros endpoints e, se forem chamados cedo demais, podem gerar erros. Por exemplo, se você estiver atribuindo um alias aos usuários pelo nosso endpoint /user/alias/new e, depois, usar esse alias para enviar um evento personalizado pelo nosso endpoint /users/track, quanto tempo você deve esperar?

Em condições normais, o tempo para a consistência eventual dos nossos dados é de 10 a 100 ms (1/10 de segundo). No entanto, em alguns casos essa consistência pode demorar mais. Por isso, recomendamos 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 o código 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 específicos de cada endpoint e o 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 a cada 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ê poderá 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.

New Stuff!