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 pela API falha.

Tipos de respostas de erro

As APIs do Excel no Microsoft Graph retornam dois tipos de erros. Uma delas é 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>
}

O segundo é do padrão de operação de longa execução, que pode retornar um 200 OK código http status e failed status de 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.

Observação

Respostas de erro seguem a definição na especificação OData v4 para respostas de erro.

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

O objeto innerError pode conter mais 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 e na mensagem 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 longa execução

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

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

Para o padrão de operação de execução longa e o padrão regular, o cliente deve primeiro analisar os códigos de erro de segundo nível necessários e manuseá-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 voltar para códigos de erro de nível superior ou códigos de status.

Os códigos de erro são insensíveis a casos.

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.

Código	Instruções
accessConflict	A solicitação com falha entra em conflito com outros clientes que acessam a pasta de trabalho (por exemplo, outro cliente bloqueou a pasta de trabalho para edição). O cliente do Microsoft Graph não deverá reenviar a solicitação com falha até que o conflito seja resolvido. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes sobre o conflito.
badRequestUncategorized	Um erro não especificado é encontrado na solicitação com falha. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
conflictUncategorized	A solicitação com falha entra em conflito com determinado estado do servidor. O cliente do Microsoft Graph não deverá reenviar a solicitação com falha até que o conflito seja resolvido. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes sobre o conflito.
forbiddenUncategorized	A solicitação com falha não é permitida. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes sobre as restrições.
gatewayTimeoutUncategorized	O serviço não pôde concluir a solicitação dentro do limite de tempo.
internalServerErrorUncategorized	Ocorreu um erro não especificado. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha. Se uma sessão for especificada na solicitação com falha, também não será esperado acesso adicional à sessão.
invalidSessionAccessConflict	A sessão especificada na solicitação é inválida devido a conflitos com outros clientes que estão acessando a pasta de trabalho (por exemplo, outro cliente bloqueou a pasta de trabalho para edição). Não é esperado acesso adicional à sessão especificada na solicitação com falha. A recriação de sessões com a mesma solicitação createSession não é esperada até que o conflito seja resolvido. Recriar sessões com uma solicitação createSession diferente pode ou não ter êxito. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes sobre o conflito.
invalidSessionAuthentication	A sessão especificada na solicitação é inválida devido a um erro de autenticação. Não é esperado acesso adicional à sessão especificada na solicitação com falha. A recriação de sessões com a mesma solicitação createSession não é esperada até que as informações de autenticação apropriadas sejam fornecidas.
invalidSessionNotFound	A sessão especificada na solicitação é inválida porque a pasta de trabalho não pode ser encontrada. Não é esperado acesso adicional à sessão especificada na solicitação com falha. Não é esperado recriar sessões com a mesma solicitação createSession .
invalidSessionReCreatable	A sessão especificada na solicitação não existe ou é inválida devido a um erro transitório. O cliente do Microsoft Graph pode tentar recriar uma sessão e retomar o trabalho. Não é esperado acesso adicional à sessão especificada na solicitação com falha.
invalidSessionRestricted	A sessão especificada na solicitação é inválida devido a configurações de serviço ou restrições. Não é esperado acesso adicional à sessão especificada na solicitação com falha. A recriação de sessões com a mesma solicitação createSession não é esperada até que as restrições ou configurações que bloqueiam a solicitação sejam alteradas. Recriar sessões com uma solicitação createSession diferente pode ou não ter êxito. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes sobre as restrições.
invalidSessionUnexpected	A sessão especificada na solicitação é inválida devido a um problema inesperado. Não é esperado acesso adicional à sessão especificada na solicitação com falha. Não é esperado recriar sessões com a mesma solicitação createSession . Recriar sessões com uma solicitação createSession diferente pode ou não ter êxito.
invalidSessionUnsupportedWorkbook	A sessão especificada na solicitação é inválida porque a pasta de trabalho contém recursos sem suporte ou excede o limite de tamanho. Normalmente, os fatores sem suporte são introduzidos por outro cliente que acessa a pasta de trabalho. Não é esperado acesso adicional à sessão especificada na solicitação com falha. A recriação de sessões com a mesma solicitação createSession não é esperada até que os fatores sem suporte sejam removidos. Recriar sessões com uma solicitação createSession diferente pode ou não ter êxito. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes dos fatores sem suporte ou com o Excel Desktop em que a pasta de trabalho pode ter suporte.
methodNotAllowedUncategorized	O método HTTP especificado na solicitação não é permitido no recurso. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
notFoundUncategorized	O recurso solicitado não pode ser encontrado. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
notImplementedUncategorized	O recurso solicitado não está implementado no momento. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
payloadTooLargeUncategorized	A carga de solicitação excede o limite de tamanho. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
serviceUnavailableUncategorized	O serviço está temporariamente indisponível ou está sobrecarregado. O cliente do Microsoft Graph não deverá reenviar a solicitação com falha até que a duração de resfriamento especificada passe.
tooManyRequestsUncategorized	A solicitação com falha excede determinada limitação de frequência. O cliente do Microsoft Graph não deverá reenviar a solicitação com falha até que a duração de resfriamento especificada passe. Para que as práticas recomendadas reduzam a limitação, consulte Reduzir erros de limitação.
transientFailure	A solicitação falhou devido a um erro transitório. O cliente do Microsoft Graph não deverá reenviar a solicitação com falha até que a duração de resfriamento especificada passe.
unauthorizedUncategorized	As informações de autenticação necessárias para o recurso estão ausentes ou inválidas. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
unsupportedWorkbook	A solicitação falhou. A pasta de trabalho contém recursos sem suporte ou excede o limite de tamanho. O cliente do Microsoft Graph não deverá reenviar a solicitação com falha até que os fatores sem suporte sejam removidos.

Observação

Para o padrão regular, a solicitação com falha é definida como a solicitação que corresponde à resposta. Para o padrão de operação de execução longa, a solicitação com falha é aquela que dispara a operação com falha.

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.

Código	Instruções
accessDenied	Você não pode executar a operação solicitada (por exemplo, executando alterações em células bloqueadas). Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
filteredRangeConflict	A operação falhou porque entra em conflito com um intervalo filtrado. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
generalException	Ocorreu um erro interno durante o processamento da solicitação. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
insertDeleteConflict	A tentativa de operação de exclusão ou inserção resultou em um conflito. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha. Um usuário final pode optar por executar manualmente as mesmas operações com o Excel Online para obter mais detalhes sobre o conflito.
invalidArgument	O argumento é inválido, ausente ou tem um formato incorreto. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
invalidReference	Esta referência não é válida para a operação atual. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
itemAlreadyExists	O recurso que está sendo criado já existe. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
itemNotFound	O recurso solicitado não existe. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
methodNotAllowed	O método HTTP especificado na solicitação não é permitido no recurso. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
nonBlankCellOffSheet	Não é possível inserir novas células porque ela empurraria células não vazias para fora do final da planilha. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha. Um usuário final pode excluir linhas ou colunas para abrir espaço para que o conteúdo seja inserido e tente novamente.
rangeExceedsLimit	A contagem de células no intervalo excedeu o número máximo com suporte. O cliente do Microsoft Graph pode tentar enviar uma solicitação com tamanho de intervalo menor. Para obter mais informações, confira Limites de recursos e otimização de desempenho para suplementos do Office.
requestAborted	A solicitação foi anulada durante o tempo de execução, o que geralmente foi causado pelo cálculo de longo tempo das funções na pasta de trabalho. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.
unsupportedOperation	Não há suporte para a operação que está sendo tentada. Não é esperado que o cliente do Microsoft Graph reenvia a solicitação com falha.

Observação

Para o padrão regular, a solicitação com falha é definida como a solicitação que corresponde à resposta. Para o padrão de operação de execução longa, a solicitação com falha é aquela que dispara a operação com falha.

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

Se você não conseguir encontrar nenhum código de erro conhecido de segundo nível, deverá seguir as instruções fornecidas para erros de nível superior. Os códigos de erro de nível superior estão associados ao código status e você pode agir de acordo com os códigos de status correspondentes. Para obter detalhes sobre códigos de erro e mensagens de nível superior, consulte Códigos de erro e mensagens.

4. Analisar o código status

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

5. Resfriamento de recuperação de erro

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

Informações de diagnóstico

Todos os conteúdos na resposta que não são usados nas etapas anteriores são apenas para diagnóstico finalidade (incluindo cadeias de caracteres nos campos de mensagem). Não recomendamos que você tenha uma dependência desses conteúdos, pois eles podem ser alterados sem aviso prévio.

Tratamento de caso especial

Para solicitações com sessão, se você encontrar um 502/badGateway ou 503/serviceUnavailable erro, 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