Lidar com erros da API REST

  • Artigo

As respostas de erro HTTP estão divididas em duas categorias:

  • Erro de cliente (nível de código 400) – o cliente enviou um pedido inválido ou o pedido não está de acordo com as definições.
  • Erro do servidor (500 níveis) – o servidor falhou temporariamente ao satisfazer o pedido ou ocorreu um erro do servidor. Tente enviar o pedido HTTP novamente.

Os códigos de erro listados na tabela seguinte podem ser devolvidos por uma operação em qualquer uma das APIs Microsoft Defender para Endpoint.

  • Além do código de erro, cada resposta de erro contém uma mensagem de erro, que pode ajudar a resolver o problema.
  • A mensagem é um texto livre que pode ser alterado.
  • Na parte inferior da página, pode encontrar exemplos de resposta.

Aplica-se a:

Quer experimentar o Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Código de erro Código de estado HTTP Mensagem
BadRequest BadRequest (400) Mensagem de erro Pedido Incorreto Geral.
ODataError BadRequest (400) Consulta URI OData inválida (o erro específico é especificado).
InvalidInput BadRequest (400) Entrada inválida {a entrada inválida}.
InvalidRequestBody BadRequest (400) Corpo do pedido inválido.
InvalidHashValue BadRequest (400) O valor hash {o hash} inválido é inválido.
InvalidDomainName BadRequest (400) Nome de domínio {o domínio inválido} é inválido.
InvalidIpAddress BadRequest (400) Endereço IP {o IP inválido} é inválido.
InvalidUrl BadRequest (400) URL {o URL inválido} é inválido.
MaximumBatchSizeExceeded BadRequest (400) Tamanho máximo do lote excedido. Recebido: {batch size received}, allowed: {batch size allowed}.
MissingRequiredParameter BadRequest (400) O parâmetro {o parâmetro em falta} está em falta.
OsPlatformNotSupported BadRequest (400) A Plataforma do SO {the client OS Platform} não é suportada para esta ação.
ClientVersionNotSupported BadRequest (400) {A ação pedida} é suportada na versão de cliente {versão suportada do cliente} e superior.
Não autorizado Não autorizado (401) Não autorizado (cabeçalho de autorização inválido ou expirado).
Proibido Proibido (403) Proibido (token válido, mas permissão insuficiente para a ação).
DisabledFeature Proibido (403) A funcionalidade de inquilino não está ativada.
DisallowedOperation Proibido (403) {a operação não permitida e o motivo}.
NotFound Não Encontrado (404) Mensagem de erro Geral Não Encontrada.
ResourceNotFound Não Encontrado (404) O recurso {o recurso pedido} não foi encontrado.
TooManyRequests Demasiados Pedidos (429) A resposta representa atingir o limite de quota por número de pedidos ou pela CPU.
InternalServerError Erro interno do Servidor (500) (Sem mensagem de erro, repita a operação.)

Limitação

O cliente HTTP pode receber um erro "Demasiados Pedidos (429)" quando o número de pedidos HTTP num determinado período de tempo excede o número permitido de chamadas por API.

O cliente HTTP deve atrasar a reenviação de pedidos HTTPS adicionais e, em seguida, submetê-los de uma forma que cumpra as limitações de taxa. Uma Retry-After no cabeçalho de resposta que indica quanto tempo esperar (em segundos) antes de fazer um novo pedido

Ignorar a resposta 429 ou tentar submeter novamente pedidos HTTP num período de tempo mais curto dá uma devolução do código de erro 429.

Os parâmetros do corpo são sensíveis às maiúsculas e minúsculas

Os parâmetros do corpo submetidos são atualmente sensíveis às maiúsculas e minúsculas.

Se ocorrer um erro InvalidRequestBody ou MissingRequiredParameter , este poderá ser causado por uma letra minúscula ou maiúscula do parâmetro errada.

Reveja a página documentação da API e verifique se os parâmetros submetidos correspondem ao exemplo relevante.

ID do pedido de correlação

Cada resposta de erro contém um parâmetro de ID exclusivo para controlo.

O nome da propriedade deste parâmetro é "target".

Ao contactar-nos relativamente a um erro, anexar este ID ajuda a encontrar a causa principal do problema.

Exemplos

{
    "error": {
        "code": "ResourceNotFound",
        "message": "Machine 123123123 was not found",
        "target": "43f4cb08-8fac-4b65-9db1-745c2ae65f3a"
    }
}

{
    "error": {
        "code": "InvalidRequestBody",
        "message": "Request body is incorrect",
        "target": "1fa66c0f-18bd-4133-b378-36d76f3a2ba0"
    }
}

Sugestão

Quer saber mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.