Tratamento de erros para APIs do Excel

Este artigo fornece instruções gerais e sugestões para lidar com erros retornados pelas APIs do Excel no Microsoft Graph quando uma solicitação enviada por meio da API falha.

Tipos de respostas de erro

As APIs do Excel no Microsoft Graph retornam dois tipos de erros. Uma é a resposta de erro regular, que se parece com a seguinte.

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

{
  "error": <Error object>
}

A segunda é do padrão de operação de longa execução, que pode retornar um 200 OK código de status HTTP e failed o status da operação no corpo da resposta, como no exemplo a seguir.

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

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

Para ambas as respostas de erro, o objeto de erro tem a estrutura a seguir.

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

O objeto innerError pode conter recursivamente mais objetos innerError com códigos de erro adicionais mais específicos. Por exemplo, o objeto de erro pode conter informações de erro mais detalhadas no código e na mensagem de erro de segundo nível, 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" }
  }
}

Etapas para lidar com respostas de erro

Espera-se que os clientes do Microsoft Graph usem as etapas a seguir para lidar com erros que ocorrem com APIs do Excel.

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

Antes de lidar com um erro, a primeira etapa é determinar se a resposta do erro é de um padrão de operação de longa duração ou de um padrão regular. Um erro de operação de execução prolongada retornará um código de status HTTP e failed o 200 OK status da operação no corpo da resposta. Uma resposta de erro regular retornará um código de status de erro HTTP correspondente.

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

Para o padrão de operação de longa duração e o padrão regular, o cliente deve primeiro analisar os códigos de erro de segundo nível necessários e tratá-los de acordo com as instruções. Opcionalmente, o cliente também pode lidar com outros códigos de erro de segundo nível ou optar por recorrer a códigos de erro de nível superior ou códigos de status.

Os códigos de erro não diferenciam maiúsculas de minúsculas.

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

A tabela a seguir lista instruções para códigos de erro de segundo nível necessários que os clientes do Microsoft Graph devem manipular. O serviço pode adicionar novos códigos de erro a qualquer momento.

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

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

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, você deverá 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 você pode executar uma ação de acordo com os códigos de status correspondentes. Para obter detalhes sobre códigos de erro e mensagens de nível superior, consulte Mensagens e códigos de erro.

4. Analise o código de status

Para o padrão regular, se você não encontrar nenhum código de erro de segundo nível conhecido ou código de erro de nível superior, deverá agir de acordo com o código de status HTTP.

5. Tempo de espera da recuperação de erros

Para algumas das respostas no padrão regular, uma duração de espera de recuperação em segundos pode ser fornecida por meio de um Retry-After cabeçalho. Quando uma duração de espera de recuperação está presente, não se espera que o cliente do Microsoft Graph envie nenhuma solicitação de acompanhamento antes que a duração especificada passe. Para obter práticas recomendadas relacionadas a Retry-After cabeçalho e limitação, consulte Reduzir erros de limitação.

Informações de diagnóstico

Todo o conteúdo da resposta que não é usado nas etapas anteriores é apenas para fins de diagnóstico (incluindo cadeias de caracteres nos campos de mensagem). Não recomendamos que você dependa desses conteúdos, pois eles podem ser alterados sem aviso prévio.

Tratamento de casos especiais

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

Conteúdo relacionado

• Usar a API REST do Excel