Table of contents

Codici errore e gestione degli errori | Concetti relativi all'API GraphError codes and error handling | Graph API concepts

Jimaco Brannian|Ultimo aggiornamento: 19/06/2018
|
2 Collaboratori

Si applica a: API Graph | Azure Active Directory (AD)Applies to: Graph API | Azure Active Directory (AD)

Le applicazioni client che usano l'API Azure Active Directory (AD) Graph devono implementare la logica di gestione degli errori per reagire nel modo più appropriato a condizioni variabili e offrire la migliore esperienza possibile ai clienti. Client applications that use the Azure Active Directory (AD) Graph API should implement error handling logic to react as gracefully as possible to varying conditions and provide the best experience possible to their customers.Questo argomento illustra i tipi di errori restituiti dal'API di Azure AD Graph e fornisce linee guida generali su come gestirli.The topic discusses the types of errors that the Azure AD Graph API returns and provides general guidance on how to handle them.

Importante

Per accedere alle risorse di Azure Active Directory è fortemente consigliabile usare Microsoft Graph anziché l'API di Azure AD Graph.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Le attività di sviluppo Microsoft sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti per l'API di Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Può essere ancora opportuno usare questa API in un numero molto limitato di scenari. Per altre informazioni, vedere il post di blog Microsoft Graph or the Azure AD Graph (Microsoft Graph o Azure AD Graph) in Office Developer Center.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Gestione degli errori dell'API Graph Handling Graph API errors

Tipi di erroriTypes of errors

Gli errori dell'API Graph si verificano nelle categorie seguenti.Graph API errors occur in the following categories.

  • Errori del client.Client Errors.Gli errori del client sono rappresentati dai codici di stato HTTP della serie 400.Client errors are represented by 400-series HTTP status codes.Includono oggetti con valori non validi, oggetti in cui mancano proprietà o valori di proprietà obbligatori, tentativi di accesso a risorse non esistenti, tentativi di aggiornamento di proprietà di sola lettura e omissione dei token di autorizzazione necessari.They include objects with invalid values, objects that are missing required properties or property values, attempting to access a non-existent resource, attempting to update a read-only property, and omitting the required authorization token.Per risolvere questi errori, risolvere innanzitutto il problema sottostante prima di inviare di nuovo la richiesta.To resolve these errors, fix the underlying issue before retrying the request.
  • Errori del server.Server Errors.Gli errori del server sono rappresentati dai codici di stato HTTP della serie 500, come ad esempio un errore della directory temporaneo.Server errors are represented by 500-series HTTP status codes, such as a transient directory failure.In genere si tratta di errori temporanei che possono essere risolti inviando di nuovo la richiesta.Most of these errors are transient and can be resolved by retrying the request.
  • Errori di rete/protocollo.Network/Protocol Errors.Durante l'invio di una richiesta o la ricezione di una risposta, possono verificarsi numerosi errori relativi alla rete, ad esempio errori di risoluzione del nome host, connessioni chiuse prematuramente ed errori di negoziazione SSL.A variety of network-related errors can occur while sending a request or receiving a response, such as host name resolution errors, prematurely closed connections, and SSL negotiation errors.La maggior parte di questi errori non si risolve con un nuovo tentativo in quanto è necessario risolvere il problema sottostante.Most of these errors cannot be resolved by retrying; the underlying issue has to be fixed.Alcuni errori, tuttavia, come ad esempio gli errori di risoluzione del nome host o i timeout, potrebbero risolversi inviando di nuovo la richiesta.However, some errors, such as host-name resolution failures or timeouts, might be resolved by retrying the request.

Struttura dei messaggi di erroreError message structure

Gli errori dell'API Graph presentano un corpo formattato composto da un codice di stato HTTP, un messaggio e i valori.Graph API errors have a formatted body that consists of an HTTP status code, a message, and values.Usare le proprietà del corpo della risposta dell'errore nella logica di gestione degli errori.Use the properties of the error body in your error handling logic.

Nota: alcune risposte HTTP potrebbero tuttavia non includere il corpo della risposta con codice, messaggio e valori perché la richiesta è instradata tramite servizi proxy e gateway.Note: Some HTTP responses might not include the code/message/values response body because the request is routed through proxy and gateway services.Accertarsi di includere la logica predefinita in grado di gestire gli errori solo in base al codice di stato HTTP.Be sure to include default logic that can handle errors based on the HTTP status code alone.

Di seguito è riportato un errore HTTP 400 Request_BadRequest.The following is an example of an HTTP 400 Request_BadRequest error.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

Ogni corpo del messaggio include le proprietà code, message e values.Each message body has code, message, and values properties.

  • Code: progettare la logica di gestione degli errori in base al codice.Code: Design your error-handling logic to branch based on the code.

    "code" : "Request_BadRequest"
    
  • Message: tupla linguaggio-valore che rappresenta un messaggio di errore leggibile.Message: A language/value tuple that represents a human-readable error message.Il contenuto si trova nel campo value.The content is in the value field.Nell'esempio seguente la richiesta non riesce perché manca il valore della proprietà mailNickname.In the following example, the request fails because the value of the mailNickname property is missing.

    "message" : {
         "lang" : "en",
         "value" : "A value is required for property 'mailNickname' of resource 'Group'."
    }
    
  • Values: raccolta di coppie nome-valore che fornisce altre informazioni sulla natura dell'errore.Values: A collection of name/value pairs that provide more information about the nature of the failure.Nell'esempio seguente non è incluso alcun valore.In the following example no values are included.

    "values" : null
    

Informazioni di riferimento per i codici di errore Error code reference

Codici di errore HTTP HTTP error codes

La tabella seguente elenca i codici errore e i messaggi di errore dell'API Graph e le azioni da eseguire per correggere gli errori.The following table lists Graph API error codes, error messages, and actions to consider when correcting errors.

In genere gli errori serie HTTP 500 si risolvono con la ripetizione dei tentativi, preferibilmente distribuiti in intervalli di tempo sempre più lunghi ("tentativo con un intervallo di backoff") e con un fattore di distribuzione casuale.In general, HTTP 500-series errors respond to retries, preferably distributed over increasingly long time intervals ("retry with a back-off interval") and with a random distribution factor.Gli errori serie 400 indicano un problema che deve essere corretto prima di ritentare.400-series errors indicate a problem that must be fixed before retrying.

Codice di stato HTTPHTTP Status CodeCodice erroreError codeMessaggio di erroreError messageDettagliDetails
400400Directory_ExpiredPageTokenDirectory_ExpiredPageTokenIl valore token della pagina specificato è scaduto e non può più essere incluso nella richiesta.The specified page token value has expired and can no longer be included in your request.
400400Directory_ResultSizeLimitExceededDirectory_ResultSizeLimitExceededIl limite delle dimensioni del risultato è stato superatoResult Size Limit was ExceededLa richiesta non può essere eseguita perché è associata a un numero eccessivo di risultati.The request cannot be fulfilled because it is associated with too many results.Questo errore si verifica molto raramente.This error occurs very infrequently.
400400DomainVerificationCodeNotFoundDomainVerificationCodeNotFoundImpossibile verificare il dominio perché il processo di verifica non riesce a trovare il record TXT con il codice di verifica corrispondente.Domain verification fails because the verification process cannot find the TXT record with matching verification code.
400400ObjectConflictObjectConflictIl nome di dominio esiste già in un dominio non verificato della società.The domain name already exists in an unverified domain in this company.
400400ObjectConflictObjectConflictIl nome di dominio esiste già in un dominio verificato della società.The domain name already exists in a verified domain in this company.
400400ObjectInUseObjectInUseImpossibile eliminare il dominio a cui attualmente fa riferimento un utente, un gruppo o un'applicazione multi-tenantCannot delete the domain currently referenced by a user, group or multi-tenant application
400400ObjectPendingDeletionObjectPendingDeletionImpossibile verificare un dominio esistente in attesa di eliminazione.Cannot verify a an existing domain which is pending deletion.
400400ObjectPendingTakeoverObjectPendingTakeoverImpossibile eliminare un dominio durante il processo di acquisizione di un tenantCannot delete a domain in the process of a tenant takeover
400400Request_BadRequestRequest_BadRequestRichiesta non valida.Bad request.Correggere la richiesta prima di ritentare.Please fix the request before retrying.Indica un errore nella richiesta, ad esempio un valore di proprietà non valido o un argomento di query non supportato.Indicates an error in the request, such as an invalid property value or an unsupported query argument.Correggere la richiesta prima di ritentare.Fix the request before retrying.
400400Request_DataContractVersionMissingRequest_DataContractVersionMissingManca il parametro della versione del contratto dati.Data contract version parameter is missing.Includere il parametro api-version come parametro di query in tutte le richieste.Include api-version as a query parameter with all your requests.
400400Request_InvalidDataContractVersionRequest_InvalidDataContractVersionIl parametro api-version specificato non è valido.The specified api-version is invalid.Il valore deve corrispondere esattamente a una versione supportata.The value must exactly match a supported version.
400400Request_InvalidRequestUrlRequest_InvalidRequestUrlL'URL della richiesta non è valido.Request url was invalid.La richiesta deve essere /tenantdomainname/Entity or /$metadata.The request should be like /tenantdomainname/Entity or /$metadata.Il nome di dominio tenant può essere un qualsiasi nome di dominio verificato, non verificato o ID contesto.Tenant domain name can be any of the verified, unverified domain names or context id.
400400Request_UnsupportedQueryRequest_UnsupportedQueryLa richiesta GET non è supportata.The GET request is unsupported.Correggere i parametri della richiesta e riprovare.Fix the request parameters and try again.
401401Authentication_ExpiredTokenAuthentication_ExpiredTokenIl token di accesso è scaduto.Your access token has expired.Rinnovarlo prima di inviare la richiesta.Please renew it before submitting the request.Il token di accesso è scaduto.Access token has expired.Rinnovare il token e inviare nuovamente.Renew the token and then resubmit.
401401Authentication_MissingOrMalformedAuthentication_MissingOrMalformedToken di accesso mancante o in formato non valido.Access Token missing or malformed.Il valore access_token nell'intestazione di autorizzazione manca o presenta un formato non valido.The access_token value in the authorization header is missing or malformed.Questo valore è obbligatorio.This value is required.Utilizzare il valore del token di autenticazione.Use the value in the authentication token.
401401Authorization_IdentityDisabledAuthorization_IdentityDisabledL'entità di applicazione chiamante è disabilitata.The calling application principal is disabled.L'entità specificata nel token di accesso è presente nella directory, ma è disabilitata.The principal specified in the access token is in the directory, but is it disabled.Riabilitare l'account nella directory e riprovare.Re-enable the account in the directory, and try again.
401401Authorization_IdentityNotFoundAuthorization_IdentityNotFoundImpossibile stabilire l'identità dell'applicazione chiamante.The identity of the calling application could not be established.L'entità specificata nel token di accesso non è stata trovata nella directory.The principal specified in the access token was not found in the directory.Questa situazione potrebbe verificarsi perché il token non è aggiornato, l'entità è stata eliminata dalla directory o la sincronizzazione della directory è posticipata.This might occur because the token is stale, the principal was deleted from the directory, or directory synchronization is delayed.
403403Authentication_UnauthorizedAuthentication_UnauthorizedRichiesta non autorizzata.Unauthorized request.Il token contiene richieste non valide o non supportate.The token contains invalid or unsupported claims.Ottenere nuovamente il token di richiesta e quindi ripetere la richiesta.Get the request token again and then retry the request.
403403Authorization_RequestDeniedAuthorization_RequestDeniedLe credenziali specificate non dispongono di privilegi sufficienti per eseguire la richiesta.The specified credentials do not have sufficient privileges to make this request.La richiesta viene negata a causa di privilegi non sufficienti.The request is denied due to insufficient privileges.Ad esempio, un'entità non amministrativa non dispone delle autorizzazioni per eliminare una risorsa.For example, a non-administrative principal does not have permission to delete a resource.
403403Directory_QuotaExceededDirectory_QuotaExceededIl limite di quota dell'oggetto directory per {tenantName} è stato superato.The directory object quota limit for the {tenantName} has been exceeded.Chiedere all'amministratore di aumentare il limite di quota o eliminare oggetti per ridurre la quota utilizzata.Please ask your administrator to increase the quota limit or delete objects to reduce the used quota.Quota di directory superata.A directory quota has been exceeded.Il tenant potrebbe contenere troppi oggetti o gli oggetti potrebbero contenere troppi valori.The tenant might have too many objects or the objects might have too many values.Questo si verifica anche quando vengono creati troppi oggetti per l'entità.This also occurs when too many objects are created on for the principal.Aumentare il valore massimo del numero di oggetti consentito per il tenant o l'entità oppure ridurre il numero di valori incluso nella richiesta o nell'aggiornamento.Increase the maximum allowed object count for the tenant or principal, or reduce the number of values included in the create/update request.
404404Directory_ObjectNotFoundDirectory_ObjectNotFoundImpossibile leggere le informazioni sulla società dalla directory.Unable to read the company information from the directory.
404404Request_ResourceNotFoundRequest_ResourceNotFoundLa risorsa {resource} non esiste o uno degli oggetti della proprietà riferimento su cui viene eseguita la query non è presente.Resource {resource} does not exist or one of its queried reference-property objects are not present.La risorsa identificata dall'URI non esiste.The resource identified by the URI does not exist.Esaminare il valore e ripetere la richiesta.Revise the value and retry the request.
409409Request_MultipleObjectsWithSameKeyValueRequest_MultipleObjectsWithSameKeyValuePrevista una risorsa singola per il risultato, ma sono state trovate più risorse.A single resource was expected for the result, but multiple resources were found.Aggiornare l'oggetto per risolvere il conflitto.Please update the object(s) to resolve the conflict.Questo errore può verificarsi quando due o più oggetti hanno lo stesso valore chiave, ad esempio se due utenti hanno lo stesso valore di UserPrincipalName.This error can occur when there are two or more objects that have the same key value, e.g. when two users have the same UserPrincipalName.
429429Troppe richieste.Too Many Requests.Questo errore si verifica quando le richieste sono limitate.This error occurs when requests are being throttled.Nel valore Retry-After dell'intestazione della risposta viene restituito un tempo di attesa consigliato.A suggested wait time is returned in the Retry-After value of the response header.Ripetere la richiesta dopo il numero consigliato di secondi di attesa.Retry the request after waiting the recommended number of seconds.
500500Service_InternalServerErrorService_InternalServerErrorErrore interno del server.Encountered an internal server error.Errore interno del server durante l'elaborazione della richiesta.Internal server error while processing the request.
502502[All][All]“... Servizio non disponibile..."“... Service Unavailable...”Un server che funge da gateway o proxy ha rilevato un errore da un altro server durante l'elaborazione della richiesta.A server acting as a gateway or proxy encountered an error from another server while processing the request.Attendere alcuni minuti e quindi ripetere la richiesta.Wait a few minutes and then retry the request.
503503Directory_ConcurrencyViolationDirectory_ConcurrencyViolationErrore dovuto a richieste simultanee al tenant.Error due to concurrent requests being made to the tenant.Attendere alcuni istanti e riprovare.Please wait briefly and retry.
503503Errore durante la verifica del DNS (nota: può essere causato da vari motivi, ad esempio il DNS non attivo).Error encountered during DNS verification (note: Can be caused by various reasons such as DNS is currently down).
Authentication_UnknownAuthentication_UnknownErrore interno del server.Internal server error.Questo codice di errore viene utilizzato quando non si applicano altri codici di errore.This error code is used when other error codes do not apply.
Authentication_UnsupportedTokenTypeAuthentication_UnsupportedTokenTypeIl tipo di token presentato non è gestito.The type of token presented is not handled.Solo i token di connessione sono supportati.Only bearer tokens are supported.Tipo di token non supportato.The token type is not supported.Controllare il tipo di token prima di ritentare la richiesta.Revise the token type before trying the request again.
Directory_BindingRedirectionDirectory_BindingRedirectionLe informazioni sul tenant non sono disponibili localmente.Tenant information is not available locally.Utilizzare i seguenti URL per ottenere le informazioni.Use the following Urls to get the information.Se la partizione di inquilino non è disponibile nei datacenter, i client devono connettersi all'URL restituito nella risposta.When the tenant partition is not available in the datacenter, clients must connect to the URl returned in the response.
Directory_BindingRedirectionInternalServerErrorDirectory_BindingRedirectionInternalServerErrorLe informazioni sul tenant non sono disponibili localmente.Tenant information is not available locally.Il server ha rilevato un errore interno durante il tentativo di popolare gli endpoint di datacenter più vicini.The server encountered an internal error while trying to populate the nearest datacenter endpoints.Quando si verifica un'eccezione di reindirizzamento di associazione, l'elenco degli endpoint di datacenter più vicini viene popolato per il servizio.When a binding redirection exception occurs, the list of nearest datacenter endpoints for the service is populated.Questo errore indica un'eccezione durante il popolamento dell'elenco.This error indicates an exception when populating the list.Provare a eseguire nuovamente la query.Try the query again.
Directory_CompanyNotFoundDirectory_CompanyNotFoundImpossibile leggere le informazioni sulla società dalla directory.Unable to read the company information from the directory.Errore durante il caricamento delle informazioni sulla società dal servizio directory.An error occurred while loading company information from the directory service.
Directory_ReplicaUnavailableDirectory_ReplicaUnavailableLa replica preferita non è disponibile.The preferred replica is unavailable.Ripetere l'operazione senza alcuna intestazione della chiave della sessione di replica.Please retry without any replica session key header.Omettere l'intestazione x-ms-replica-session-key e riprovare.Omit the x-ms-replica-session-key header and then retry.
Headers_DataContractVersionMissingHeaders_DataContractVersionMissingIntestazione della versione del contratto dati mancante.The data contract version header is missing.Includere x-ms-dirapi-data-contract-version nella richiesta.Include x-ms-dirapi-data-contract-version in your request.Versione del contratto del client mancante nella richiesta.The client contract version is missing from the request.
Headers_HeaderNotSupportedHeaders_HeaderNotSupportedL'intestazione {0} non è attualmente non supportata.Header {0} is not currently supported.La richiesta contiene un'intestazione HTTP non supportata.The request contains an unsupported HTTP header.Modificare l'intestazione e ripetere la richiesta.Change the header and try the request again.
Request_InvalidReplicaSessionKeyRequest_InvalidReplicaSessionKeyLa chiave della sessione di replica specificata non è valida.The replica session key provided is not valid.Correggere la chiave della sessione di replica e ripetere la richiesta.Fix the replica session key and try the request again.
Request_ThrottledPermanentlyRequest_ThrottledPermanentlyLa richiesta è limitata in modo permanente.Your request is throttled permanently.Chiamare il supporto tecnico per risolvere il problema.Please call support to address the issue.Il tenant ha superato ripetutamente e in modo persistente il limite di frequenza della richiesta di token.The tenant repeatedly and persistently exceeded the token request rate limit.Le richieste dal tenant vengono rifiutate finché il servizio non viene rinegoziato.Requests from the tenant are rejected until the service is renegotiated.Contattare il supporto tecnico Microsoft per assistenza.For help, contact Microsoft Support.

Risorse aggiuntive Additional resources

© 2018 Microsoft