Processamento de erros para APIs do Excel

Este artigo fornece instruções gerais e sugestões para lidar com erros que são devolvidos pelas APIs do Excel no Microsoft Graph quando um pedido enviado através da API falha.

Tipos de respostas de erro

As APIs do Excel no Microsoft Graph devolvem dois tipos de erros. Uma delas é a resposta de erro regular, que se assemelha ao seguinte.

HTTP/1.1 <HTTP status code>
Content-type: application/json
Retry-After: <Cooldown duration in seconds> (optional)

{
  "error": <Error object>
}

O segundo é do padrão de operação de execução prolongada, que pode devolver um 200 OK código http status e failed uma operação status no corpo da resposta, como no exemplo seguinte.

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "failed",
  "error": <Error object>
}

Para ambas estas respostas de erro, o objeto de erro tem a seguinte estrutura.

{
  "code": "string",
  "message": "string",
  "innerError": { "@odata.type": "odata.error" }
}

O objeto innerError pode conter recursivamente objetos innerError com códigos de erro adicionais e mais específicos. Por exemplo, o objeto de erro pode conter informações de erro mais detalhadas no código de erro de segundo nível e na mensagem, conforme mostrado.

{
  "code": "Top-level error code",
  "message": "Top-level error message",
  "innerError": {
    "code": "Second-level error code",
    "message": "Second-level error message",
    "innerError": { "@odata.type": "odata.error" }
  }
}

Passos para processar respostas de erros

Espera-se que os clientes do Microsoft Graph utilizem os seguintes passos para lidar com erros que ocorrem com as APIs do Excel.

1. Determinar se é um erro de operação de execução prolongada

Antes de processar um erro, o primeiro passo é determinar se a resposta do erro provém de um padrão de operação de execução prolongada ou de um padrão regular. Um erro de operação de execução prolongada devolverá um 200 OK código http status e failed uma operação status no corpo da resposta. Uma resposta de erro regular devolverá um erro HTTP correspondente status código.

2. Analisar código de erro de segundo nível

Tanto para o padrão de operação de execução prolongada como para o padrão regular, o cliente deve primeiro analisar os códigos de erro de segundo nível necessários e processá-los de acordo com as instruções. Opcionalmente, o cliente também pode processar outros códigos de erro de segundo nível ou optar por reverter para códigos de erro de nível superior ou códigos de status.

Os códigos de erro não são sensíveis a maiúsculas e minúsculas.

Códigos de erro de segundo nível necessários

A tabela seguinte lista as instruções para os códigos de erro de segundo nível necessários que os clientes do Microsoft Graph devem processar. O serviço pode adicionar novos códigos de erro em qualquer altura.

Exemplos opcionais de código de erro de segundo nível

A tabela seguinte lista exemplos de códigos de erro opcionais de segundo nível, incluindo as instruções de processamento correspondentes para cada código de erro. O serviço pode adicionar novos códigos de erro em qualquer altura.

3. Analisar o código de erro de nível superior

Se não encontrar nenhum código de erro de segundo nível conhecido, deve seguir as instruções fornecidas para erros de nível superior. Os códigos de erro de nível superior estão vinculados ao código de status e pode tomar medidas de acordo com os códigos de status correspondentes. Para obter detalhes sobre códigos de erro e mensagens de nível superior, veja Códigos de erro e mensagens.

4. Analisar o código de status

Para o padrão normal, se não conseguir encontrar nenhum código de erro de segundo nível conhecido ou código de erro de nível superior, deve tomar medidas de acordo com o código de status HTTP.

5. Erro de recuperação de cooldown

Para algumas das respostas no padrão normal, pode ser fornecida uma duração de arrefecimento da recuperação em segundos através de um Retry-After cabeçalho. Quando está presente uma duração de arrefecimento de recuperação, não é esperado que o cliente do Microsoft Graph envie pedidos de seguimento antes da duração especificada passar. Para obter as melhores práticas relacionadas com o Retry-After cabeçalho e a limitação, veja Reduzir erros de limitação.

Informações de diagnóstico

Todos os conteúdos na resposta que não são utilizados nos passos anteriores destinam-se apenas a diagnóstico finalidade (incluindo cadeias nos campos da mensagem). Não recomendamos que assuma uma dependência destes conteúdos, uma vez que estes podem ser alterados sem aviso prévio.

Processamento de casos especiais

Para pedidos com sessão, se encontrar um 502/badGateway erro ou 503/serviceUnavailable , quando for encontrado um código de erro de segundo nível conhecido, siga as instruções correspondentes; caso contrário, deve recriar a sessão diretamente.

Conteúdo relacionado

• Usar a API REST do Excel