Gestione degli errori dell'API REST

Le risposte agli errori HTTP sono suddivise in due categorie:

• Errore del client (livello di codice 400): il client ha inviato una richiesta non valida o la richiesta non è conforme alle definizioni.
• Errore del server (livello 500): il server non è riuscito temporaneamente a soddisfare la richiesta o si è verificato un errore del server. Provare a inviare di nuovo la richiesta HTTP.

I codici di errore elencati nella tabella seguente possono essere restituiti da un'operazione su una qualsiasi delle API Microsoft Defender per endpoint.

• Oltre al codice di errore, ogni risposta di errore contiene un messaggio di errore che consente di risolvere il problema.
• Il messaggio è un testo libero che può essere modificato.
• Nella parte inferiore della pagina sono disponibili esempi di risposta.

Codice errore	Codice di stato HTTP	Messaggio
BadRequest	BadRequest (400)	Messaggio di errore Generale richiesta non valida.
ODataError	BadRequest (400)	Query URI OData non valida (viene specificato l'errore specifico).
InvalidInput	BadRequest (400)	Input non valido {input non valido}.
InvalidRequestBody	BadRequest (400)	Corpo della richiesta non valido.
InvalidHashValue	BadRequest (400)	Valore hash {l'hash non valido} non è valido.
InvalidDomainName	BadRequest (400)	Il nome di dominio {il dominio non valido} non è valido.
InvalidIpAddress	BadRequest (400)	Indirizzo IP {l'INDIRIZZO IP non valido} non è valido.
InvalidUrl	BadRequest (400)	URL {l'URL non valido} non è valido.
MaximumBatchSizeExceeded	BadRequest (400)	La dimensione massima del batch è stata superata. Ricevuto: {batch size received}, allowed: {batch size allowed}.
MissingRequiredParameter	BadRequest (400)	Parametro {il parametro mancante} mancante.
OsPlatformNotSupported	BadRequest (400)	La piattaforma del sistema operativo {piattaforma del sistema operativo client} non è supportata per questa azione.
ClientVersionNotSupported	BadRequest (400)	{L'azione richiesta} è supportata nella versione client {versione client supportata} e versioni successive.
Non autorizzato	Non autorizzato (401)	Non autorizzato (intestazione di autorizzazione non valida o scaduta).
Operazione non consentita	Accesso negato (403)	Accesso negato (token valido ma autorizzazione insufficiente per l'azione).
DisabledFeature	Accesso negato (403)	La funzionalità tenant non è abilitata.
DisallowedOperation	Accesso negato (403)	{l'operazione non consentita e il motivo}.
NotFound	Non trovato (404)	Messaggio di errore Generale non trovato.
ResourceNotFound	Non trovato (404)	La risorsa {la risorsa richiesta} non è stata trovata.
TooManyRequests	Troppe richieste (429)	La risposta rappresenta il raggiungimento del limite di quota in base al numero di richieste o alla CPU.
InternalServerError	Errore interno del server (500)	(Nessun messaggio di errore, riprovare l'operazione).

Strozzatura

Il client HTTP potrebbe ricevere un errore "Troppe richieste (429)" quando il numero di richieste HTTP in un determinato intervallo di tempo supera il numero consentito di chiamate per API.

Il client HTTP deve ritardare la reinvio di ulteriori richieste HTTPS e quindi inviarle in modo conforme alle limitazioni di frequenza. Un Retry-After nell'intestazione di risposta che indica quanto tempo attendere (in secondi) prima di effettuare una nuova richiesta

Ignorare la risposta 429 o provare a inviare di nuovo le richieste HTTP in un intervallo di tempo più breve restituisce il codice di errore 429.

I parametri del corpo fanno distinzione tra maiuscole e minuscole

I parametri del corpo inviati fanno attualmente distinzione tra maiuscole e minuscole.

Se si verificano errori InvalidRequestBody o MissingRequiredParameter , potrebbe essere causato da una lettera maiuscola del parametro errata o minuscola.

Esaminare la pagina della documentazione dell'API e verificare che i parametri inviati corrispondano all'esempio pertinente.

ID richiesta di correlazione

Ogni risposta di errore contiene un parametro ID univoco per il rilevamento.

Il nome della proprietà di questo parametro è "target".

Quando ci contatta per un errore, allegare questo ID consente di trovare la causa radice del problema.

Esempi

{
    "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"
    }
}

Consiglio

Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender per endpoint Tech Community.