Limitação em Microsoft Fabric

O Microsoft Fabric usa a limitação de taxa para manter o desempenho e a confiabilidade do serviço quando as cargas de trabalho excedem a capacidade ou os limites de solicitações da API REST. Este artigo explica como funciona a limitação de taxa, como interpretar respostas HTTP 429 e como projetar aplicativos que lidam de forma eficaz com as cotas da API do Fabric.

Limites de quota da API

Microsoft Fabric está introduzindo a Cota Unificada para APIs REST para suas APIs REST. Nesse modelo, as solicitações de API são regidas por cotas de nível de identidade impostas por Usuário ou Entidade de Serviço.

A meta é uma experiência de limitação de taxa consistente e previsível para os grupos de API governados, em cenários de automação, CI/CD e orientados por agentes.

Anteriormente, cada API REST do Microsoft Fabric aplicava suas próprias regras independentes de limitação de taxa, o que frequentemente resultava em comportamento inconsistente entre endpoints. Como resultado, era difícil prever quando uma carga de trabalho poderia ser limitada, especialmente para cenários de automação que interagiram com várias APIs e estavam sujeitos a limites diferentes.

Com a introdução da Cota de APIs, Fabric está migrando para uma abordagem mais consistente e baseada em identidade. O consumo da API agora é governado por uma cota unificada, aplicada por identidade, o que proporciona um modelo de limitação de taxa mais claro e previsível nas APIs do Fabric. No entanto, é importante observar que alguns limites de limitação específicos da API individuais ainda podem ser aplicados além da cota geral de APIs.

Quando uma página de referência de API documenta uma cota, trate esse limite específico do ponto de extremidade como autoritativo para essa API. Se uma página de referência de API não listar uma cota numérica, crie seu aplicativo para lidar com 429 respostas respeitando Retry-After, aplicando novas tentativas limitadas e evitando intermitências.

Como funciona o modelo de cota

Cada identidade, um usuário ou uma entidade de serviço, recebe vários buckets de cota independentes que regem diferentes categorias de tráfego de API. Quando a identidade envia uma solicitação, a solicitação é avaliada em relação à cota da categoria de API que está sendo usada.

Há três Cotas Unificadas:

1. Cota unificada para APIs de plataforma — dedicada às APIs de plataforma.
2. Cota unificada para APIs do Agendador de Trabalho — dedicada às APIs do Agendador de Trabalho.
3. Cota unificada para APIs de operações de longa duração — dedicada às APIs de operações de longa duração.

Como essas cotas são independentes, a atividade em uma categoria não consome cota de outra categoria. Por exemplo, uma entidade de serviço poderia consumir toda a sua Cota Unificada para as APIs do Agendador de Tarefas sem afetar a Cota Unificada disponível para as APIs de Plataforma. Essa separação garante que cargas de trabalho de alto volume em áreas de API especializadas não afetem operações gerais de API e permitem um comportamento de limitação mais previsível em diferentes tipos de solicitações.

Aplicação da API

A Cota de APIs é imposta por identidade, o que significa que cada usuário, entidade de serviço ou identidade gerenciada recebe sua própria alocação de cota independente. As cotas nunca são compartilhadas entre identidades e todas as APIs de Fabric qualificadas consomem de um bucket de cota comum associado a essa identidade.

Como resultado, o uso da API por uma identidade não afeta nenhuma outra identidade. Por exemplo, um principal de serviço muito utilizado pode esgotar sua própria cota de API sem afetar as cotas de outros usuários ou aplicativos.

Da mesma forma, se uma identidade atingir seu limite de cota e for limitada, essa limitação se aplicará somente a essa identidade, enquanto outras identidades continuarão operando normalmente. Esse isolamento fornece um consumo de API mais previsível e gerenciável entre cargas de trabalho.

Hierarquia de imposição de cotas

Cada solicitação de API começa com uma identidade, uma conta de usuário ou uma entidade de serviço. Quando essa identidade faz uma chamada à API do Fabric, a solicitação primeiro consome capacidade da cota compartilhada de APIs, que é aplicada por identidade, e não por API. Essa cota atua como um mecanismo de limitação centralizado que é compartilhado em todas as APIs participantes, garantindo que uma única identidade não possa exceder sua taxa de solicitação alocada.

Depois que a solicitação é avaliada com base na cota compartilhada das APIs, quaisquer limites de controle de taxa específicos de cada API também são aplicados. Esses limites são independentes da cota compartilhada e podem existir apenas para determinadas APIs. Como resultado, uma solicitação deve atender à Cota de APIs no nível da identidade e a todos os limites de API individuais aplicáveis a serem processados com êxito.

Em termos práticos, a Cota de APIs compartilhadas fornece uma experiência de limitação consistente entre APIs, enquanto os limites de API individuais continuam a proteger serviços específicos que exigem proteções adicionais. Portanto, uma chamada à API pode ser limitada porque a identidade esgotou sua cota compartilhada ou porque atingiu o limite de um ponto de extremidade de API específico.

Conceitos-chave:

• Imposição baseada em identidade: a cota é controlada separadamente para cada usuário ou entidade de serviço.
• Compartilhado entre APIs: as solicitações para APIs diferentes consomem do mesmo pool de cotas de APIs.
• Limitação somente: a cota de APIs controla as taxas de solicitação, mas não afeta a autorização ou as permissões.
• Aplicação dupla: tanto a cota compartilhada de APIs quanto os limites específicos da API são verificados em cada solicitação.
• O limite mais restritivo vence: uma solicitação é limitada quando a cota compartilhada ou um limite específico da API aplicável é excedido.

Como a cota é consumida

Cada solicitação de API consome a cota do bucket de cota de APIs da identidade que faz a chamada. Todas as solicitações feitas por essa identidade contam para a mesma cota compartilhada, independentemente de qual API é chamada.

Período de Cota e Renovação

A cota de APIs é imposta usando uma janela fixa de 60 segundos. O reservatório de cota é reabastecido integralmente quando a janela atual se encerra. A cota não se recupera gradualmente durante a janela.

Exemplo de linha do tempo

Second 0   → Quota window begins. Bucket is full (300 requests available).
Second 1   → 300 requests are made. Bucket is exhausted.
             Additional requests receive HTTP 429 (Too Many Requests).

Seconds 2-59 → All additional requests continue to receive HTTP 429.
               No quota is restored during the window.

Second 60  → New quota window begins.
             Bucket is fully replenished (300 requests available).
             Requests are accepted again.

Implicações práticas

• O estouro de solicitações no início de uma janela é permitido, mas isso pode deixar a identidade limitada pelo restante dessa janela.
• Distribuir solicitações uniformemente no período de 60 segundos ajuda a evitar a limitação.
• Sempre respeite o cabeçalho de resposta Retry-After. Indica quanto tempo aguardar antes de tentar novamente uma solicitação limitada.

Detalhes do limite de taxa por API

Embora a Microsoft Fabric forneça categorias de limitação unificadas e conceitos de cota compartilhada, os limites de taxa reais podem variar de acordo com a API. Sempre verifique a seção de limites de throttling da API específica que você está chamando.

Mensagem de limitação

Quando ocorre limitação de taxa, o Fabric retorna um código de status HTTP 429 (Solicitações em excesso). Fabric retorna um código de status 429 por dois motivos distintos, cada um identificado por um diferente errorCode no corpo da resposta:

• Limite de taxa excedido (RequestBlocked)
• Limite de capacidade excedido (CapacityLimitExceeded)

Inspecione o errorCode valor na resposta para determinar qual condição ocorreu e como responder.

Limite de taxa excedido (RequestBlocked)

Quando um usuário envia muitas solicitações que excedem um limite predeterminado durante uma janela de tempo, Fabric limita outras solicitações desse usuário por um curto período.

Nesse caso, Fabric retorna um código de status HTTP 429 (muitas solicitações) com um Retry-After cabeçalho HTTP na resposta, indicando quantos segundos o aplicativo de chamada deve aguardar antes de repetir a chamada. O corpo da resposta usa o RequestBlocked código de erro:

{
    "errorCode": "RequestBlocked",
    "message": "Request is blocked by the upstream service until: 2/18/2026 10:45:04 PM (UTC)"
}

Quando receber esse erro, aguarde a duração especificada no Retry-After cabeçalho antes de repetir a solicitação.

A captura de tela a seguir mostra um exemplo de resposta, sugerindo que o usuário espera 55 segundos antes de repetir a chamada.

Limite de capacidade excedido (CapacityLimitExceeded)

Fabric também retorna um código de status HTTP 429 (muitas solicitações) quando a capacidade de Fabric da sua organização excedeu seus limites. Ao contrário da limitação de taxa, essa restrição não é causada pelo número de chamadas de API que um cliente específico realiza. Em vez disso, isso ocorre quando a capacidade de computação (unidades de capacidade) consumida na sua capacidade excede os limites da SKU do Fabric adquirida. O corpo da resposta usa o CapacityLimitExceeded código de erro:

{
    "errorCode": "CapacityLimitExceeded",
    "message": "Your organization's Fabric compute capacity has exceeded its limits. Try again later."
}

Quando receber esse erro, tente a solicitação novamente mais tarde. Como essa limitação depende da capacidade computacional total consumida na sua capacidade, e não da sua taxa individual de solicitações, é improvável que tentar novamente imediatamente funcione até que o uso computacional da capacidade volte a ficar dentro dos limites. Se você encontrar esse erro com frequência, considere escalar verticalmente ou horizontalmente a capacidade do Fabric. Para obter mais informações sobre unidades de capacidade, SKUs e como a capacidade do Fabric é consumida, consulte Planejar o tamanho da capacidade.

Considerações e limitações

Cada Fabric administrador e a API pública principal podem ser limitadas.

Tenha estas considerações em mente ao criar aplicativos que chamam Fabric APIs REST:

• As cotas são impostas para a identidade do chamador e a API que está sendo chamada. Identidades separadas não necessariamente compartilham o mesmo contador de solicitação, mas cada chamador ainda deve seguir os limites documentados para a API.
• Muitos limites de taxa são avaliados em janelas de um minuto. Se você exceder um limite, aguarde o Retry-After valor antes de enviar mais solicitações.
• A limitação de capacidade é diferente da limitação da taxa de solicitação. CapacityLimitExceededindica que a capacidade de Fabric está sobrecarregada, não que o chamador tenha excedido uma cota de API por minuto.
• Tentar novamente imediatamente após um erro de limitação de capacidade provavelmente não terá êxito. Use uma política de repetição limitada e investigue o uso da capacidade se o erro persistir.
• Para integrações de alto volume, prefira operações de lista, massa ou lote quando estiverem disponíveis, armazene metadados que são alterados com pouca frequência e espalhem solicitações uniformemente ao longo do tempo.
• Para APIs que dão suporte à paginação, use tokens de continuação em vez de fazer consultas amplas repetidas desde o início.

Perguntas frequentes

Como saber se alcancei uma cota de API ou um limite de capacidade?

Verifique o errorCode no corpo da resposta 429. RequestBlocked significa que a taxa de solicitação excedeu os limites de limitação do serviço. CapacityLimitExceeded significa que a capacidade de computação consumida na capacidade do Fabric excedeu os limites da SKU adquirida.

Quando minha quota é renovada?

Muitos limites de taxa da API REST do Fabric são avaliados em intervalos de um minuto. Se a resposta incluir um Retry-After cabeçalho, use esse valor como o tempo de espera autoritativo antes de tentar novamente.

Posso verificar minha cota de API restante antes de fazer uma solicitação?

As respostas da API REST do Fabric não fornecem um contador geral da cota restante para todas as APIs. Crie clientes para que eles possam detectar 429 respostas, honrar Retry-Aftere reduzir o volume de solicitação durante a limitação.

Como posso reduzir a chance de ter minha velocidade reduzida?

Use operações em massa e em lote quando disponíveis, prefira APIs de lista em vez de muitas chamadas de recurso único, armazene em cache metadados acessados com frequência e evite picos repentinos de tráfego. Para limitação persistente da capacidade, use o aplicativo de Métricas de Capacidade do Microsoft Fabric para identificar capacidades e cargas de trabalho sobrecarregadas.

Devo repetir cada resposta 429 da mesma maneira?

Não. Para RequestBlocked, aguarde o cabeçalho Retry-After e tente novamente com uma política de novas tentativas com limite. Para CapacityLimitExceeded, tente novamente mais tarde, com recuo exponencial, e investigue a utilização de capacidade se o problema continuar.

Conteúdo relacionado

• Usando as APIs REST do Microsoft Fabric
• Escopos
• Solucionar problemas de APIs REST do Microsoft Fabric
• Planejar o tamanho da capacidade
• Entenda a limitação da sua capacidade do Fabric
• Aplicativo Microsoft Fabric Capacity Metrics