Respostas de erros e tipos de recurso do Microsoft Graph

  • Artigo

Os erros no Microsoft Graph são retornados usando códigos HTTP status padrão e um objeto de resposta a erro JSON.

Códigos de status de HTTP

A tabela a seguir lista e descreve os códigos de status HTTP que podem ser retornados.

Código de status Mensagem de status Descrição
400 Solicitação Incorreta (Bad Request) Não é possível processar a solicitação porque ela está malformada ou incorreta.
401 Não Autorizado (Unauthorized) As informações de autenticação necessárias estão ausentes ou não são válidas para o recurso.
402 Pagamento necessário Os requisitos de pagamento da API não foram atendidos.
403 Proibido Acesso negado ao recurso solicitado. O usuário pode não ter permissão suficiente ou talvez não tenha uma licença necessária.

Importante: Se as políticas de acesso condicional forem aplicadas a um recurso, uma HTTP 403; Forbidden error=insufficient_claims mensagem poderá ser retornada. Para obter mais informações sobre o Microsoft Graph e o acesso condicional, consulte Diretrizes do desenvolvedor para acesso condicional Microsoft Entra.
404 Não Encontrado (Not Found) O recurso solicitado não existe.
405 Método Não Permitido (Method Not Allowed) O método HTTP na solicitação não é permitido no recurso.
406 Não Aceitável (Not Acceptable) Esse serviço não dá suporte ao formato solicitado no cabeçalho Accept.
409 Conflito O estado atual está em conflito com o que a solicitação espera. Por exemplo, a pasta pai especificada não existe.
410 Sumiu (Gone) O recurso solicitado não está mais disponível no servidor.
411 Comprimento Solicitado (Length Required) É necessário um cabeçalho Content-Length na solicitação.
412 Falha na Pré-condição (Precondition Failed) Uma pré-condição fornecida na solicitação (como um cabeçalho if-match) não corresponde ao estado atual do recurso.
413 Entidade de Solicitação Muito Grande (Request Entity Too Large) O tamanho da solicitação excede o limite máximo.
415 Tipo de Mídia Não Suportado (Unsupported Media Type) O tipo de conteúdo da solicitação é um formato que não tem suporte do serviço.
416 Intervalo Solicitado Não Satisfatório (Requested Range Not Satisfiable) O intervalo de bytes especificado é inválido ou está indisponível.
422 Entidade Não Processável (Unprocessable Entity) Não é possível processar a solicitação porque ela está semanticamente incorreta.
423 Bloqueado O recurso acessado está bloqueado.
429 Muitos Pedidos (Too Many Requests) O aplicativo cliente foi limitado e não deve tentar repetir a solicitação até que um período de tempo tenha decorrido.
500 Erro Interno do Servidor (Internal Server Error) Ocorreu um erro interno do servidor ao processar a solicitação.
501 Não Implementado (Not Implemented) O recurso solicitado não foi implementado.
503 Serviço Indisponível O serviço está temporariamente indisponível para manutenção ou está sobrecarregado. Você pode repetir a solicitação após um atraso, cujo comprimento pode ser especificado em um cabeçalho Retry-After.
504 Tempo Limite do Gateway (Gateway Timeout) O servidor, enquanto atuava como proxy, não recebeu uma resposta oportuna do servidor upstream que precisava acessar na tentativa de concluir a solicitação.
507 Armazenamento Insuficiente (Insufficient Storage) A cota máxima de armazenamento foi atingida.
509 Limite de Largura de Banda Excedido Seu aplicativo foi limitado por exceder o limite máximo de largura de banda. O aplicativo pode tentar a solicitação novamente depois de decorrido algum tempo.

A resposta de erro é um único objeto JSON que contém uma propriedade única chamada error. Esse objeto inclui todos os detalhes do erro. Você pode usar as informações retornadas aqui em vez de ou além do código de status HTTP. Este é um exemplo de um corpo de erro JSON completo.

{
  "error": {
    "code": "badRequest",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "code": "invalidRange",
      "request-id": "request-id",
      "date": "date-time"
    }
  }
}

Tipo de recurso de erro

O recurso de erro será retornado sempre que ocorrer um erro no processamento de uma solicitação.

As respostas de erro seguem a definição nas Diretrizes da API REST da Microsoft.

Representação JSON

O recurso de erro é composto por um único recurso:

{
  "error": {
    "code": "string",
    "message": "string",
    "innererror": { 
      "code": "string"
    },
    "details": []
  }
}
Nome da propriedade Valor Descrição
code string Uma cadeia de códigos de erro para a falha que ocorreu
message string Uma mensagem pronta para o desenvolvedor sobre o erro que ocorreu. Isso não deve ser exibido diretamente para o usuário.
innererror objeto error Opcional. Um objeto de erro adicional que pode ser mais específico do que o erro de nível superior.
detalhes error object Opcional. Uma lista de objetos de erro adicionais que podem fornecer uma divisão de vários erros encontrados durante o processamento da solicitação.

Propriedades

A propriedade code contém um valor legível pelo computador no qual você pode usar uma dependência em seu código.

O objeto innererror pode conter de forma recursiva mais objetos innererror com propriedades de códigos de erro adicionais e mais específicas . Ao lidar com um erro, os aplicativos devem percorrer todos os códigos de erro aninhados disponíveis e usar o mais detalhado que eles entendem.

A propriedade da mensagem é um valor legível pelo homem que descreve a condição de erro. Não tenha nenhuma dependência do conteúdo desse valor em seu código.

A propriedade de mensagem na raiz contém uma mensagem de erro destinada ao desenvolvedor a ler. As mensagens de erro não são localizadas e não devem ser exibidas diretamente para o usuário. Ao lidar com erros, seu código não deve ter nenhuma dependência dos valores da propriedade da mensagem porque eles podem ser alterados a qualquer momento e geralmente contêm informações dinâmicas específicas para a solicitação com falha. Você só deve codificar contra códigos de erro retornados em propriedades de código .

A propriedade details é uma matriz opcional de objetos de erro que têm o mesmo formato JSON que o objeto de erro de nível superior. No caso de uma solicitação composta por várias operações, como uma operação em massa ou em lote, talvez seja necessário retornar um erro independente para cada operação. Nesse caso, a lista de detalhes é preenchida com esses erros individuais.