Compartilhar via

Respostas de erros e tipos de recurso do Microsoft Graph

  • Artigo

Os erros no Microsoft Graph são devolvidos com códigos de status HTTP padrão e um objeto de resposta de 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 o pedido porque está incorreto ou incorreto.
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 Obrigatório Os requisitos de pagamento da API não foram cumpridos.
403 Proibido Acesso negado ao recurso solicitado. O utilizador pode não ter permissão suficiente ou pode não ter uma licença necessária.

Importante: Se forem aplicadas políticas de acesso condicional a um recurso, poderá ser devolvida uma HTTP 403; Forbidden error=insufficient_claims mensagem. Para obter mais informações sobre o Microsoft Graph e o acesso condicional, veja Orientações para Programadores para Microsoft Entra Acesso Condicional.
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 no pedido 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 no pedido (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 do pedido é um formato que não é suportado pelo 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 o pedido porque está semanticamente incorreto.
423 Bloqueado O recurso acessado está bloqueado.
429 Muitos Pedidos (Too Many Requests) A aplicação cliente foi limitada e não deve tentar repetir o pedido até que decorra um período de tempo.
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 atempadamente do servidor upstream a que precisava para aceder na tentativa de concluir o pedido.
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 programador sobre o erro que ocorreu. Isto não deve ser apresentado diretamente ao utilizador.
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 discriminação de vários erros encontrados durante o processamento do pedido.

Propriedades

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

O objeto innererror pode conter recursivamente objetos mais internos com propriedades de códigos de erro adicionais e mais específicas. Ao processar um erro, as aplicações devem percorrer todos os códigos de erro aninhados que estão disponíveis e utilizar o mais detalhado que entenderem.

A propriedade da mensagem é um valor legível por humanos que descreve a condição de erro. Não assuma nenhuma dependência do conteúdo deste valor no seu código.

A propriedade da mensagem na raiz contém uma mensagem de erro destinada ao programador a ler. As mensagens de erro não são localizadas e não devem ser apresentadas diretamente ao utilizador. Ao processar erros, o código não deve assumir qualquer dependência dos valores da propriedade da mensagem , uma vez que podem ser alterados em qualquer altura e, muitas vezes, contêm informações dinâmicas específicas do pedido falhado. Só deve codificar os códigos de erro devolvidos nas propriedades do 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 um pedido composto por várias operações, como uma operação em massa ou em lote, poderá ser necessário devolver um erro independente para cada operação. Neste caso, a lista de detalhes é preenchida com estes erros individuais.