Solucionar problemas de APIs REST do Microsoft Fabric

Introdução

Este artigo ajuda você a entender e solucionar problemas de erros comuns retornados pelas APIs REST do Microsoft Fabric. Ele explica o formato de erro padrão usado pelo serviço e fornece diretrizes para resolver os códigos de status HTTP encontrados com mais frequência.

Entender as respostas de erro do Microsoft Fabric

Quando ocorre um erro ao processar uma solicitação para a API REST do Microsoft Fabric, o serviço retorna um objeto padrão ErrorResponse no corpo da resposta.

Ao solucionar problemas, sempre capture e registre o requestId, pois ele identifica exclusivamente a solicitação e é necessário quando se entra em contato com o suporte técnico da Microsoft. A ID da solicitação está disponível no corpo da resposta e nos cabeçalhos de resposta.

Importante

  • errorCode os valores são estáveis e baseados em contrato.
  • 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 esse valor ao implementar a lógica de tratamento de erros.
message string Uma descrição do erro legível para humanos.
moreDetails ErrorResponseDetails[] Lista opcional de detalhes de erro adicionais.
relatedResource ErrorRelatedResource Informações sobre o recurso associado ao erro, se aplicável.
requestId string O identificador exclusivo da solicitação com falha. Inclua esse valor ao entrar em contato com o suporte da Microsoft.

Esquema de Detalhes de ErroResposta

Fornece contexto adicional para cenários de erro complexos.

Nome Tipo Description
errorCode string Um identificador estável que descreve os detalhes de erro específicos.
message string Uma explicação legível pelo ser humano dos detalhes do erro.
relatedResource ErrorRelatedResource O recurso associado a este detalhe de erro específico.

Esquema de Recurso Relacionado ao Erro

Identifica o recurso envolvido no erro.

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

Cenários comuns de erro HTTP

As seções a seguir descrevem códigos de status HTTP comuns retornados pelas APIs REST do Microsoft Fabric, juntamente com causas raiz típicas e resoluções recomendadas.

API retorna 401 – Não autorizada

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

Causas comuns

Código do erro Description Resolução
TokenExpired O token de acesso expirou. Adquira um novo token de acesso e repita a solicitação.
InsufficientScopes O token de acesso não inclui os escopos necessários. Atualize o aplicativo para solicitar os escopos necessários conforme documentado na especificação da API ou atualize o registro do aplicativo no Microsoft Entra.

API retorna 403 – Proibido

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

Causas comuns

Código do erro Description Resolução
InsufficientPrivileges O chamador não tem as permissões necessárias para acessar o recurso. Peça a um administrador de workspace ou de recursos para conceder permissões suficientes ao usuário que está chamando ou à entidade de serviço.

API retorna 404 – Não encontrado

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

Observação

APIs individuais podem definir códigos de erro adicionais específicos à API. Sempre consulte a especificação da API para obter detalhes autoritativos.

Causas comuns

Código do erro Description Resolução
WorkspaceNotFound Não foi possível encontrar o workspace especificado. Verifique se o ID correto do objeto do workspace foi fornecido.
EntityNotFound Não foi possível encontrar o recurso solicitado. Confirme se a ID de recurso correta foi fornecida. A entidade ausente é identificada no relatedResource campo da resposta de erro.

API retorna 429 – Muitas solicitações

Uma resposta 429 indica que a solicitação foi restringida devido ao limite de taxa. Microsoft Fabric retorna um código de status 429 por dois motivos distintos, cada um identificado por um diferente errorCode no corpo da resposta.

Causas comuns

Código do erro Description Resolução
RequestBlocked A taxa de solicitação excedeu os limites de limitação do serviço. Aguarde a duração especificada no Retry-After cabeçalho antes de tentar novamente. Consulte Lidar com a limitação de taxa no seu aplicativo.
CapacityLimitExceeded A computação (unidades de capacidade) consumida em sua capacidade excedeu os limites da SKU de Fabric adquirida. Repita a solicitação mais tarde. Consulte Controle de capacidade.

Limitação de taxa (RequestBlocked)

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

  • A limitação é imposta por identidade de chamador.
  • Normalmente, os limites de taxa são avaliados em janelas de um minuto.

Informações sobre o tempo de tentativa

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

  • Corpo da 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 aguardar antes de tentar novamente.

Sempre prefira o Retry-After cabeçalho ao implementar a lógica de tentativas.

Manipular a limitação de taxa em seu aplicativo

Os aplicativos devem:

  • Detectar respostas HTTP 429.
  • Analise e honre o cabeçalho Retry-After.
  • Aplique uma política de repetição limitada, como retirada exponencial com tremulação para cenários de alta escala.
  • Evite loops de repetição infinitos.

Reduzir a probabilidade de limitação de taxa

  • Use operações em massa e em lote quando disponível.
  • Prefira listar APIs em vez de solicitações de recurso único repetidas.
  • Armazenar em cache dados acessados com frequência, especialmente metadados que são alterados com pouca frequência.
  • Evite intermitências de tráfego distribuindo solicitações uniformemente ao longo do tempo.

Limite de capacidade excedido (CapacityLimitExceeded)

Um CapacityLimitExceeded erro indica que a computação (unidades de capacidade) consumida em sua capacidade excedeu os limites da SKU Fabric adquirida. Ao contrário da limitação de taxa, essa restrição não é causada pelo número de chamadas à API feitas por um chamador específico; ela reflete o consumo total de computação em todas as cargas de trabalho na capacidade provisionada.

Corpo da resposta de exemplo:

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

Gerenciar a restrição de capacidade

Como essa limitação depende da capacidade computacional total consumida na sua capacidade, e não da sua taxa de solicitações individual, o cabeçalho Retry-After não se aplica, e é improvável que tentar novamente imediatamente funcione até que o uso de computação da capacidade volte a ficar dentro dos limites. Os aplicativos devem:

  • Repita a solicitação mais tarde usando uma política de repetição limitada com retirada exponencial.
  • Se o erro persistir, 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.

Resumo

A criação de integrações confiáveis com AS APIs REST do Microsoft Fabric requer um tratamento de erro robusto e padrões de solicitação eficientes. Ao compreender as respostas de erro, respeitar os sinais de limitação de taxa e otimizar os padrões de requisição, você pode criar aplicativos resilientes.

Conteúdo relacionado

Para obter perguntas adicionais ou diretrizes da comunidade, consulte a Comunidade do Microsoft Fabric

  • Last updated on