Resolução de Problemas das APIs REST do Microsoft Fabric

Introdução

Este artigo ajuda-o a compreender e a resolver erros comuns devolvidos pelas APIs REST do Microsoft Fabric. Explica o formato padrão de erro utilizado pelo serviço e fornece orientações para resolver os códigos de estado HTTP mais frequentemente encontrados.

Compreender as Respostas de Erro do Microsoft Fabric

Quando ocorre um erro durante o processamento de um pedido para a API REST do Microsoft Fabric, o serviço devolve um objeto padrão ErrorResponse no corpo da resposta.

Ao fazer resolução de problemas, capture e registre sempre o requestId, pois identifica de forma única o pedido e é necessário ao contactar o suporte da Microsoft. O ID do pedido está disponível tanto no corpo da resposta como nos cabeçalhos da resposta.

Importante

  • errorCode os valores são estáveis e baseados em contratos.
  • O texto legível message por humanos pode mudar ao longo do tempo e não deve ser analisado programaticamente.

Esquema de ErrorResponse

Nome Tipo Description
errorCode string Um identificador estável para a condição de erro. Use este valor ao implementar lógica de gestão de erros.
message string Uma descrição do erro legível por humanos.
moreDetails ErrorResponseDetails[] Lista opcional de detalhes adicionais de erro.
relatedResource ErrorRelatedResource Informação sobre o recurso associado ao erro, se aplicável.
requestId string O identificador único do pedido falhado. Inclua este valor ao contactar o suporte da Microsoft.

Esquema "ErrorResponseDetails"

Fornece contexto adicional para cenários de erro complexos.

Nome Tipo Description
errorCode string Um identificador estável que descreve o detalhe específico do erro.
message string Uma explicação legível para humanos do detalhe do erro.
relatedResource ErrorRelatedResource O recurso associado a este detalhe específico do erro.

Esquema de Recurso Relacionado a Erro

Identifica o recurso envolvido no erro.

Nome Tipo Description
resourceId string O ID do recurso envolvido no erro.
resourceType string O tipo do recurso (por exemplo, espaço de trabalho, item ou capacidade).

Cenários comuns de erro HTTP

As secções seguintes descrevem os códigos de estado HTTP comuns retornados pelas APIs REST do Microsoft Fabric, juntamente com as causas raiz típicas e as resoluções recomendadas.

API devolve 401 – Não autorizado

Uma resposta 401 indica que o pedido falhou durante a autenticação ou validação do token de acesso.

Principais causas comuns

Código de erro Description Resolução
TokenExpired O token de acesso expirou. Adquira um novo token de acesso e tente novamente o pedido.
InsufficientScopes O token de acesso não inclui os escopos necessários. Atualize a aplicação para solicitar os âmbitos de permissão necessários, conforme documentado na especificação da API, ou atualize o registo da aplicação no Microsoft Entra.

A API retorna 403 – Forbidden

Uma resposta 403 indica que o chamador está autenticado, mas não tem permissões suficientes para realizar a operação solicitada no recurso alvo.

Principais causas comuns

Código de erro Description Resolução
InsufficientPrivileges O chamador não tem as permissões necessárias para aceder ao recurso. Peça a um administrador de espaço de trabalho ou de recursos para conceder permissões suficientes ao utilizador ou principal do serviço que chama.

API devolve 404 – Não Encontrado

Uma resposta 404 indica que um recurso solicitado ou referenciado não existe ou não está acessível ao interlocutor.

Nota

As APIs individuais podem definir códigos de erro adicionais específicos de cada API. Consulte sempre a especificação da API para detalhes autoritativos.

Principais causas comuns

Código de erro Description Resolução
WorkspaceNotFound O espaço de trabalho especificado não foi encontrado. Verifique se o ID correto do objeto de trabalho foi fornecido.
EntityNotFound O recurso solicitado não foi encontrado. Confirme que o ID correto do recurso foi fornecido. A entidade em falta é identificada no relatedResource campo da resposta ao erro.

API devolve 429 – Demasiados Pedidos

Uma resposta 429 indica que o pedido foi limitado. O Microsoft Fabric devolve um código de estado 429 por duas razões distintas, cada uma identificada por um diferente errorCode no corpo da resposta.

Principais causas comuns

Código de erro Description Resolução
RequestBlocked A taxa de pedidos ultrapassou os limites de limitação do serviço. Aguarde pelo tempo especificado no Retry-After cabeçalho antes de tentar novamente. Consulte Lidar com a limitação da taxa na sua aplicação.
CapacityLimitExceeded As unidades de computação (capacidade) consumidas na sua capacidade excederam os limites do SKU Fabric adquirido. Repita a solicitação mais tarde. Veja como lidar com a limitação da capacidade.

Limitação de taxa (RequestBlocked)

Um RequestBlocked erro indica que a taxa de pedidos excedeu os limites de limitação do serviço.

  • A limitação é aplicada por identidade do chamador.
  • Os limites de taxa são normalmente avaliados ao longo de janelas de um minuto.

Informação sobre o tempo de nova tentativa

Quando ocorre limitação da taxa, são fornecidas informações sobre nova tentativa em dois locais:

  • Corpo de resposta (message)
    Exemplo:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After Cabeçalho de resposta HTTP
    Especifica o número de segundos que o cliente deve esperar antes de tentar novamente.

Prefira sempre o Retry-After cabeçalho ao implementar lógica de novas tentativas.

Gerir a limitação de taxa na sua aplicação

As candidaturas devem:

  • Detetar respostas HTTP 429.
  • Analise e respeite o Retry-After cabeçalho.
  • Aplique uma política de retentativas limitadas, como o backoff exponencial com jitter para cenários de grande escala.
  • Evita ciclos de tentativas infinitas.

Reduzir a probabilidade de limitação da taxa

  • Use operações em massa e em lote quando disponível.
  • Prefira APIs de listas a pedidos repetidos de recurso único.
  • Cache acede frequentemente aos dados, especialmente metadados que mudam raramente.
  • Evite picos de tráfego distribuindo os pedidos de forma uniforme ao longo do tempo.

Limite de capacidade excedido (CapacityLimitExceeded)

Um CapacityLimitExceeded erro indica que as unidades de computação (capacidade) consumidas na sua capacidade excederam os limites do SKU Fabric comprado. Ao contrário da limitação da taxa, esta restrição não é causada pelo número de chamadas à API que um chamador específico efetua; reflete os recursos de computação consumidos no total por todas as cargas de trabalho na capacidade.

Exemplo de corpo da resposta:

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Limitação da capacidade da alavanca

Como esta limitação depende dos recursos de computação totais consumidos pela sua capacidade, e não da taxa dos seus pedidos individuais, o cabeçalho Retry-After não é aplicável, e é pouco provável que tentar novamente de imediato tenha sucesso até que a utilização de computação da capacidade volte a situar-se dentro dos seus limites. As candidaturas devem:

  • Tente novamente o pedido mais tarde, usando uma política de repetição limitada com recuo exponencial.
  • Se o erro persistir, considere aumentar verticalmente ou expandir horizontalmente a capacidade do Fabric.

Para mais informações sobre unidades de capacidade, SKUs e como a capacidade de Fabric é consumida, consulte Planeie o tamanho da sua capacidade.

Resumo

Construir integrações fiáveis com APIs REST do Microsoft Fabric requer um tratamento robusto de erros e padrões de pedidos eficientes. Ao compreender as respostas de erro, respeitar os sinais de limitação de taxa e otimizar os padrões de pedido, pode criar aplicações resilientes.

Conteúdo relacionado

Para perguntas adicionais ou orientações da comunidade, consulte Microsoft Fabric Community

  • Last updated on