Table of contents

Códigos de erro e tratamento de erro | Conceitos da API do GraphError codes and error handling | Graph API concepts

Jimaco Brannian|Última Atualização: 19/06/2018
|
2 Colaboradores

Aplica-se a: API do Graph | Azure AD (Active Directory)Applies to: Graph API | Azure Active Directory (AD)

Os aplicativos cliente que usam a API do Graph do Azure AD (Active Directory) devem implementar a lógica de tratamento de erro para reagir da forma mais adequada possível a condições variáveis e para proporcionar a melhor experiência possível aos clientes. 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.Este tópico aborda os tipos de erros retornados pela API do Graph do Azure AD, além de fornecer diretrizes gerais sobre como lidar com eles.The topic discusses the types of errors that the Azure AD Graph API returns and provides general guidance on how to handle them.

Importante

Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office.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.

Tratando erros na API do Graph Handling Graph API errors

Tipos de errosTypes of errors

Os erros da Graph API ocorrem nas seguintes categorias.Graph API errors occur in the following categories.

  • Erros de cliente.Client Errors.Os erros de cliente são representados por códigos de status HTTP da série 400.Client errors are represented by 400-series HTTP status codes.Eles incluem objetos com valores inválidos, objetos que não têm propriedades ou valores de propriedade necessários, a tentativa de acessar um recurso inexistente, a tentativa de atualizar uma propriedade somente leitura e a omissão do token de autorização necessário.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.Para resolver esses erros, corrija o problema subjacente antes de repetir a solicitação.To resolve these errors, fix the underlying issue before retrying the request.
  • Erros de servidor.Server Errors.Os erros de servidor são representados por códigos de status HTTP da série 500, por exemplo uma falha de diretório temporária.Server errors are represented by 500-series HTTP status codes, such as a transient directory failure.A maioria desses erros é temporária e pode ser resolvida repetindo-se a solicitação.Most of these errors are transient and can be resolved by retrying the request.
  • Erros de rede/protocolo.Network/Protocol Errors.Uma variedade de erros relacionados à rede pode ocorrer durante o envio de uma solicitação ou o recebimento de uma resposta, como erros de resolução de nome de host, conexões fechadas prematuramente e erros de negociação 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.A maioria desses erros não pode ser resolvida com uma repetição; é necessário solucionar o problema subjacente.Most of these errors cannot be resolved by retrying; the underlying issue has to be fixed.No entanto, alguns erros, como as falhas de resolução de nome de host ou os erros relacionados com tempos limites, podem ser resolvidos repetindo-se a solicitação.However, some errors, such as host-name resolution failures or timeouts, might be resolved by retrying the request.

Estrutura da mensagem de erroError message structure

Os erros da Graph API têm um corpo formatado que consiste em um código de status HTTP, uma mensagem e valores.Graph API errors have a formatted body that consists of an HTTP status code, a message, and values.Use as propriedades do corpo do erro na sua lógica de tratamento de erro.Use the properties of the error body in your error handling logic.

Observação: algumas respostas HTTP podem não incluir o corpo de resposta de código/mensagem/valores pois a solicitação é encaminhada por meio de serviços de 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.Não se esqueça de incluir a lógica padrão capaz de manipular erros apenas com base no código do status HTTP.Be sure to include default logic that can handle errors based on the HTTP status code alone.

Veja a seguir um exemplo de um erro 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
    }
 }

Cada corpo de mensagem tem propriedades de código, mensagem e valores.Each message body has code, message, and values properties.

  • Código: projete sua lógica de tratamento de erros para que ela seja ramificada com base no código.Code: Design your error-handling logic to branch based on the code.

    "code" : "Request_BadRequest"
    
  • Mensagem: uma tupla linguagem/valor que representa uma mensagem de erro legível.Message: A language/value tuple that represents a human-readable error message.O conteúdo está no campo de valor.The content is in the value field.No exemplo a seguir, a solicitação falha porque o valor da propriedade mailNickname está ausente.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'."
    }
    
  • Valores: uma coleção de pares nome/valor que fornecem mais informações sobre a natureza da falha.Values: A collection of name/value pairs that provide more information about the nature of the failure.No exemplo a seguir, não são incluídos valores.In the following example no values are included.

    "values" : null
    

Referência do código de erro Error code reference

Códigos de erro HTTP HTTP error codes

A tabela a seguir lista os códigos de erro, as mensagens de erro e as ações do da API do Graph a serem considerados durante a correção dos erros.The following table lists Graph API error codes, error messages, and actions to consider when correcting errors.

Em geral, os erros HTTP 500 respondem às novas tentativas, distribuídas preferencialmente em intervalos de tempo cada vez mais longos (“repetir com um intervalo de retirada”) e com um fator de distribuição aleatório.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.Os erros da série 400 indicam um problema que deve ser solucionado antes de uma nova tentativa.400-series errors indicate a problem that must be fixed before retrying.

Código de Status HTTPHTTP Status CodeCódigo do erroError codeMensagem de erroError messageDetalhesDetails
400400Directory_ExpiredPageTokenDirectory_ExpiredPageTokenO valor do token de página especificado expirou e não pode mais ser incluído na sua solicitação.The specified page token value has expired and can no longer be included in your request.
400400Directory_ResultSizeLimitExceededDirectory_ResultSizeLimitExceededO limite de tamanho do resultado foi excedidoResult Size Limit was ExceededA solicitação não puder ser atendida porque está associada a muitos resultados.The request cannot be fulfilled because it is associated with too many results.Este erro ocorre muito raramente.This error occurs very infrequently.
400400DomainVerificationCodeNotFoundDomainVerificationCodeNotFoundA verificação do domínio falhou porque o processo de verificação não pôde localizar o registro TXT com código de verificação correspondente.Domain verification fails because the verification process cannot find the TXT record with matching verification code.
400400ObjectConflictObjectConflictO nome de domínio já existe em um domínio não verificado nesta empresa.The domain name already exists in an unverified domain in this company.
400400ObjectConflictObjectConflictO nome de domínio já existe em um domínio verificado nesta empresa.The domain name already exists in a verified domain in this company.
400400ObjectInUseObjectInUseNão foi possível excluir o domínio atualmente referenciado por um usuário, grupo ou aplicativo multilocatárioCannot delete the domain currently referenced by a user, group or multi-tenant application
400400ObjectPendingDeletionObjectPendingDeletionNão foi possível verificar um domínio existente que aguarda a exclusão.Cannot verify a an existing domain which is pending deletion.
400400ObjectPendingTakeoverObjectPendingTakeoverNão foi possível excluir um domínio no processo de tomada de controle de um locatárioCannot delete a domain in the process of a tenant takeover
400400Request_BadRequestRequest_BadRequestSolicitação inválida.Bad request.Corrija a solicitação antes de tentar novamente.Please fix the request before retrying.Indica um erro na solicitação, como um valor de propriedade inválido ou um argumento de consulta sem suporte.Indicates an error in the request, such as an invalid property value or an unsupported query argument.Corrija a solicitação antes de tentar novamente.Fix the request before retrying.
400400Request_DataContractVersionMissingRequest_DataContractVersionMissingO parâmetro da versão do contrato de dados está ausente.Data contract version parameter is missing.Inclua a versão da API como um parâmetro de consulta em todas as suas solicitações.Include api-version as a query parameter with all your requests.
400400Request_InvalidDataContractVersionRequest_InvalidDataContractVersionA versão da API especificada é inválida.The specified api-version is invalid.O valor deve corresponder exatamente a uma versão suportada.The value must exactly match a supported version.
400400Request_InvalidRequestUrlRequest_InvalidRequestUrlA URL solicitada era inválida.Request url was invalid.A solicitação deve ser como /nomededomíniodolocatário/Entidade ou /$metadados.The request should be like /tenantdomainname/Entity or /$metadata.O nome de domínio do locatário pode ser um dos nomes de domínio verificados, não verificados ou uma identificação de contexto.Tenant domain name can be any of the verified, unverified domain names or context id.
400400Request_UnsupportedQueryRequest_UnsupportedQueryA solicitação GET não tem suporte.The GET request is unsupported.Corrija os parâmetros da solicitação e tente novamente.Fix the request parameters and try again.
401401Authentication_ExpiredTokenAuthentication_ExpiredTokenO token de acesso expirou.Your access token has expired.Renove-o antes de enviar a solicitação.Please renew it before submitting the request.O token de acesso expirou.Access token has expired.Renove o token e reenvie-o.Renew the token and then resubmit.
401401Authentication_MissingOrMalformedAuthentication_MissingOrMalformedToken de acesso ausente ou inválido.Access Token missing or malformed.O valor access_token no cabeçalho de autorização está ausente ou é inválido.The access_token value in the authorization header is missing or malformed.Esse valor é necessário.This value is required.Use o valor no token de autenticação.Use the value in the authentication token.
401401Authorization_IdentityDisabledAuthorization_IdentityDisabledA entidade de segurança do aplicativo de chamada está desabilitada.The calling application principal is disabled.A entidade especificada no token de acesso está no diretório, mas ele está desabilitado.The principal specified in the access token is in the directory, but is it disabled.Habilite novamente a conta no diretório e tente novamente.Re-enable the account in the directory, and try again.
401401Authorization_IdentityNotFoundAuthorization_IdentityNotFoundA identidade do aplicativo de chamada não pôde ser estabelecida.The identity of the calling application could not be established.A entidade especificada no token de acesso não foi encontrada no diretório.The principal specified in the access token was not found in the directory.Isso pode ocorrer porque o token está desatualizado, a entidade foi excluída do diretório ou a sincronização de diretório foi adiada.This might occur because the token is stale, the principal was deleted from the directory, or directory synchronization is delayed.
403403Authentication_UnauthorizedAuthentication_UnauthorizedSolicitação não autorizada.Unauthorized request.O token contém solicitações inválidas ou sem suporte.The token contains invalid or unsupported claims.Obtenha o token de solicitação novamente e repita a solicitação.Get the request token again and then retry the request.
403403Authorization_RequestDeniedAuthorization_RequestDeniedAs credenciais especificadas não têm privilégios suficientes para fazer esta solicitação.The specified credentials do not have sufficient privileges to make this request.A solicitação foi negada devido a privilégios insuficientes.The request is denied due to insufficient privileges.Por exemplo, uma entidade de segurança não administrativa não tem permissão para excluir um recurso.For example, a non-administrative principal does not have permission to delete a resource.
403403Directory_QuotaExceededDirectory_QuotaExceededO limite de cota do objeto do diretório para o {tenantName} foi excedido.The directory object quota limit for the {tenantName} has been exceeded.Solicite ao administrador que aumente o limite de cota ou exclua objetos para reduzir a cota utilizada.Please ask your administrator to increase the quota limit or delete objects to reduce the used quota.Uma cota de diretório foi excedida.A directory quota has been exceeded.Possivelmente, o locatário tem muitos objetos ou os objetos têm muitos valores.The tenant might have too many objects or the objects might have too many values.Isso também ocorre quando muitos objetos são criados para a entidade de segurança.This also occurs when too many objects are created on for the principal.Aumente o número máximo de objetos permitidos para o locatário ou a entidade de segurança ou reduza o número de valores incluídos na solicitação de criação/atualização.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_ObjectNotFoundNão é possível ler as informações da empresa no diretório.Unable to read the company information from the directory.
404404Request_ResourceNotFoundRequest_ResourceNotFoundO recurso {recurso} não existe ou um de seus objetos de referência-propriedade consultados não está presente.Resource {resource} does not exist or one of its queried reference-property objects are not present.O recurso identificado pelo URI não existe.The resource identified by the URI does not exist.Revise o valor e repita a solicitação.Revise the value and retry the request.
409409Request_MultipleObjectsWithSameKeyValueRequest_MultipleObjectsWithSameKeyValueEra esperado um recurso único para o resultado, mas foram encontrados vários recursos.A single resource was expected for the result, but multiple resources were found.Atualize o(s) objeto(s) para resolver o conflito.Please update the object(s) to resolve the conflict.Esse erro pode ocorrer quando existem dois ou mais objetos com o mesmo valor de chave, por exemplo, quando dois usuários usam o mesmo 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.
429429Excesso de solicitações.Too Many Requests.Esse erro ocorre quando as solicitações são limitadas.This error occurs when requests are being throttled.Um tempo de espera sugerido é retornado no valor Retry-After do cabeçalho de resposta.A suggested wait time is returned in the Retry-After value of the response header.Repita a solicitação após aguardar o tempo recomendado.Retry the request after waiting the recommended number of seconds.
500500Service_InternalServerErrorService_InternalServerErrorErro de servidor interno encontrado.Encountered an internal server error.Erro de servidor interno ao processar a solicitação.Internal server error while processing the request.
502502[Tudo][All]“... Serviço não disponível....”“... Service Unavailable...”Um servidor que atua como gateway ou proxy detectou um erro em outro servidor ao processar a solicitação.A server acting as a gateway or proxy encountered an error from another server while processing the request.Espere alguns minutos e repita a solicitação.Wait a few minutes and then retry the request.
503503Directory_ConcurrencyViolationDirectory_ConcurrencyViolationErro causado por solicitações simultâneas ao locatário.Error due to concurrent requests being made to the tenant.Aguarde um instante e tente novamente.Please wait briefly and retry.
503503Erro encontrado durante a verificação de DNS (observação: pode ser causado por vários motivos como DNS atualmente inativo).Error encountered during DNS verification (note: Can be caused by various reasons such as DNS is currently down).
Authentication_UnknownAuthentication_UnknownErro de servidor interno.Internal server error.Este código de erro é usado quando outros códigos de erro não se aplicam.This error code is used when other error codes do not apply.
Authentication_UnsupportedTokenTypeAuthentication_UnsupportedTokenTypeO tipo de token apresentado não é manipulado.The type of token presented is not handled.Somente os tokens de portador têm suporte.Only bearer tokens are supported.Não há suporte para o tipo de token.The token type is not supported.Revise o tipo de token antes de tentar a solicitação novamente.Revise the token type before trying the request again.
Directory_BindingRedirectionDirectory_BindingRedirectionNão há informações de locatário disponíveis localmente.Tenant information is not available locally.Use as seguintes URLs para obter as informações.Use the following Urls to get the information.Quando a partição de locatário não está disponível no datacenter, os clientes devem se conectar ao URI retornado na resposta.When the tenant partition is not available in the datacenter, clients must connect to the URl returned in the response.
Directory_BindingRedirectionInternalServerErrorDirectory_BindingRedirectionInternalServerErrorNão há informações de locatário disponíveis localmente.Tenant information is not available locally.O servidor encontrou um erro interno ao tentar preencher os pontos de extremidade de datacenter mais próximos.The server encountered an internal error while trying to populate the nearest datacenter endpoints.Quando uma exceção de redirecionamento de associação ocorre, a lista de pontos de extremidade de datacenter mais próximos do serviço é preenchida.When a binding redirection exception occurs, the list of nearest datacenter endpoints for the service is populated.Esse erro indica uma exceção durante o preenchimento da lista.This error indicates an exception when populating the list.Tente executar a consulta novamente.Try the query again.
Directory_CompanyNotFoundDirectory_CompanyNotFoundNão é possível ler as informações da empresa no diretório.Unable to read the company information from the directory.Erro ao carregar as informações da empresa no diretório de serviço.An error occurred while loading company information from the directory service.
Directory_ReplicaUnavailableDirectory_ReplicaUnavailableA réplica preferencial não está disponível.The preferred replica is unavailable.Tente novamente sem nenhum cabeçalho de chave de sessão da réplica.Please retry without any replica session key header.Omita o cabeçalho x-ms-replica-session-key e tente novamente.Omit the x-ms-replica-session-key header and then retry.
Headers_DataContractVersionMissingHeaders_DataContractVersionMissingO cabeçalho da versão do contrato de dados está ausente.The data contract version header is missing.Inclua x-ms-dirapi-data-contract-version na solicitação.Include x-ms-dirapi-data-contract-version in your request.A versão do contrato do cliente está ausente na solicitação.The client contract version is missing from the request.
Headers_HeaderNotSupportedHeaders_HeaderNotSupportedO cabeçalho {0} não tem suporte no momento.Header {0} is not currently supported.A solicitação contém um cabeçalho HTTP sem suporte.The request contains an unsupported HTTP header.Altere o cabeçalho e tente a solicitação novamente.Change the header and try the request again.
Request_InvalidReplicaSessionKeyRequest_InvalidReplicaSessionKeyA chave de sessão de réplica fornecida não é válida.The replica session key provided is not valid.Corrija a chave de sessão de réplica e tente executa a solicitação novamente.Fix the replica session key and try the request again.
Request_ThrottledPermanentlyRequest_ThrottledPermanentlyA solicitação foi restringida definitivamente.Your request is throttled permanently.Contate a equipe de suporte para resolver o problema.Please call support to address the issue.O locatário excedeu várias vezes e com persistência o limite da taxa de solicitação de token.The tenant repeatedly and persistently exceeded the token request rate limit.As solicitações do locatário serão rejeitadas até que o serviço seja renegociado.Requests from the tenant are rejected until the service is renegotiated.Para obter ajuda, contate o Suporte da Microsoft.For help, contact Microsoft Support.

Recursos adicionais Additional resources

© 2018 Microsoft