Compartilhar via


Manipulando erros de API REST

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

  • Erro do cliente (nível de 400 códigos) – o cliente enviou uma solicitação inválida ou a solicitação não está de acordo com as definições.
  • Erro do servidor (500 níveis) – o servidor falhou temporariamente ao atender à solicitação ou ocorreu um erro do servidor. Tente enviar a solicitação HTTP novamente.

Os códigos de erro listados na tabela a seguir podem ser retornados por uma operação em qualquer uma das APIs Microsoft Defender para Ponto de Extremidade.

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

Aplica-se a:

Deseja experimentar o Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Código de erro Código de status de HTTP Mensagem
BadRequest BadRequest (400) Mensagem de erro de Solicitação Inválida 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 da solicitação inválido.
InvalidHashValue BadRequest (400) Valor de 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 {a URL} inválida é inválida.
MaximumBatchSizeExceeded BadRequest (400) Tamanho máximo do lote excedido. Recebido: {tamanho do lote recebido}, permitido: {tamanho do lote permitido}.
MissingRequiredParameter BadRequest (400) O parâmetro {o parâmetro ausente} está ausente.
OsPlatformNotSupported BadRequest (400) Plataforma do sistema operacional {a plataforma do sistema operacional cliente} não tem suporte para essa ação.
ClientVersionNotSupported BadRequest (400) {A ação solicitada} tem suporte na versão do cliente {versão do cliente compatível} e acima.
Não Autorizado (Unauthorized) 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) O recurso de locatário não está habilitado.
DisallowedOperation Proibido (403) {a operação não permitida e o motivo}.
NotFound Não encontrado (404) Mensagem de erro Geral Não Encontrado.
ResourceNotFound Não encontrado (404) Recurso {o recurso solicitado} não foi encontrado.
TooManyRequests Muitas solicitações (429) A resposta representa atingir o limite de cota por número de solicitações ou por CPU.
InternalServerError Erro interno do servidor (500) (Nenhuma mensagem de erro, tente novamente a operação.)

Limitação

O cliente HTTP pode receber um "Erro de Muitas Solicitações (429)" quando o número de solicitações HTTP em um determinado período excede o número permitido de chamadas por API.

O cliente HTTP deve atrasar a reenviação de outras solicitações HTTPS e enviá-las de uma maneira que cumpra as limitações de taxa. Um Retry-After no cabeçalho de resposta indicando quanto tempo esperar (em segundos) antes de fazer uma nova solicitação

Ignorar a resposta 429 ou tentar reenviar solicitações HTTP em um período de tempo mais curto dá um retorno do código de erro 429.

Os parâmetros do corpo são sensíveis a casos

Os parâmetros de corpo enviados atualmente são sensíveis a casos.

Se você tiver erros InvalidRequestBody ou MissingRequiredParameter , isso poderá ser causado por um capital de parâmetro errado ou uma letra de maiúsculas minúsculas.

Examine a página de documentação da API e marcar que os parâmetros enviados correspondam ao exemplo relevante.

ID da solicitação de correlação

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

O nome da propriedade desse parâmetro é "destino".

Ao entrar em contato conosco sobre um erro, anexar essa ID ajuda a encontrar a causa raiz 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"
    }
}

Dica

Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender para Ponto de Extremidade Tech Community.