Lidar com erros da API REST
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.