Códigos de error y control de errores | Conceptos de Graph API

  • Artículo

Se aplica a: Graph API | Azure Active Directory (AD)

Las aplicaciones cliente que usan la API de Azure Active Directory (AD) Graph deben implementar la lógica de control de errores para reaccionar de forma eficaz ante condiciones variables y ofrecer la mejor experiencia posible a sus clientes. Este tema analiza los tipos de errores que devuelve la API de Azure AD Graph y ofrece instrucciones generales sobre cómo controlarlos.

Importante

Se recomienda encarecidamente que use Microsoft Graph en lugar de la API de Azure AD Graph para acceder a recursos de Azure Active Directory. Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph. Hay un número muy limitado de escenarios para los que la API de Azure AD Graph todavía podría ser adecuada; para más información, vea la entrada del blog Microsoft Graph o Azure AD Graph en el centro de desarrollo de Office.

Control de errores de Graph API

Tipos de errores

Los errores de Graph API se generan en las categorías siguientes.

  • Errores del cliente. Los errores del cliente se representan mediante códigos de estado HTTP de la serie 400. Estos incluyen objetos con valores no válidos, objetos que precisan propiedades o valores de propiedad necesarios, intentos de acceso a recursos inexistentes, intentos de actualización de propiedades de solo lectura y omisión de los tokens de autorización necesarios. Para solucionar estos errores, corrija el problema subyacente antes de reintentar la solicitud.
  • Errores del servidor. Los errores del servidor se representan mediante códigos de estado HTTP de la serie 500 (por ejemplo, un error de directorio transitorio). La mayoría de estos errores son transitorios y se resuelven al reintentar la solicitud.
  • Errores de protocolo o red. Al enviar una solicitud o recibir una respuesta pueden producirse distintos errores relacionados con la red (como errores de resolución de nombres de host, conexiones que se cierran antes de tiempo y errores de negociación SSL). La mayoría de estos errores no se resuelven al reintentar la solicitud: debe corregirse el problema subyacente. No obstante, sí es posible que algunos de ellos (como los errores de tiempo de expiración o resolución de nombres de host) se resuelvan al reintentar la solicitud.

Estructura del mensaje de error

Los errores de Graph API tienen un cuerpo con formato que consta de un código de estado HTTP, un mensaje y los valores. Use las propiedades del cuerpo del error en su lógica de control de errores.

Nota: Si la solicitud se redirige a través de servicios de puerta de enlace y proxy, es posible que algunas respuestas HTTP no incluyan el cuerpo de respuesta del código, el mensaje o los valores. Asegúrese de incluir lógica predeterminada capaz de controlar los errores basándose exclusivamente en el código de estado HTTP.

A continuación se muestra un ejemplo de un error de Request_BadRequest HTTP 400.

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

El cuerpo de cada mensaje tiene propiedades de código, mensaje y valores.

  • Código: diseñe la lógica de control de errores para aplicar a la rama en función del código.

    "code" : "Request_BadRequest"

  • Mensaje: una tupla de idioma o valor que representa un mensaje de error legible para el ojo humano. El contenido se incluye en el campo de valor. En el ejemplo siguiente, la solicitud presenta un error porque falta el valor de la propiedad mailNickname.

    "message" : {
     "lang" : "en",
     "value" : "A value is required for property 'mailNickname' of resource 'Group'."
}

  • Valores: una colección de pares nombre-valor que amplían la información sobre la naturaleza del error. En el ejemplo siguiente no se incluyen valores.

    "values" : null

Referencia de código de error

Códigos de error HTTP

En la tabla siguiente se muestran los códigos de error de Graph API, mensajes de error y acciones que se deben considerar cuando se corrigen errores.

En general, los errores de la serie HTTP 500 responden a reintentos, preferiblemente distribuidos en intervalos de tiempo cada vez más largos (“reintento con un intervalo de interrupción”) y un factor de distribución aleatorio. Los errores de la serie 400 indican un problema que se debe corregir antes de reintentarlo.

Código de estado HTTP Código de error Mensaje de error Detalles
400 Directory_ExpiredPageToken El valor del token de página especificado ha expirado y ya no puede incluirse en la solicitud.
400 Directory_ResultSizeLimitExceeded Se superó el límite de tamaño de resultados. No se puede tramitar la solicitud porque está asociada a demasiados resultados. Este error se produce con muy poca frecuencia.
400 DomainVerificationCodeNotFound Se produce un error en la comprobación de dominio porque el proceso de comprobación no puede encontrar el registro TXT con el correspondiente código de verificación.
400 ObjectConflict Ya existe el nombre de dominio en un dominio no comprobado de esta empresa.
400 ObjectConflict Ya existe el nombre de dominio en un dominio comprobado de esta empresa.
400 ObjectInUse No se puede eliminar el dominio al que hace referencia actualmente un usuario, un grupo o una aplicación multiinquilino.
400 ObjectPendingDeletion No se puede comprobar un dominio existente que está pendiente de eliminación.
400 ObjectPendingTakeover No se puede eliminar un dominio en el proceso de adquisición del inquilino.
400 Request_BadRequest Solicitud incorrecta. Corrija la solicitud antes de reintentarlo. Indica un error en la solicitud, como un valor de propiedad no válido o un argumento de consulta no admitido. Corrija la solicitud antes de reintentarlo.
400 Request_DataContractVersionMissing Falta el parámetro de versión del contrato de datos. Incluya api-version como un parámetro de consulta con todas las solicitudes.
400 Request_InvalidDataContractVersion La versión de API especificada no es válida. El valor debe coincidir exactamente con una versión compatible.
400 Request_InvalidRequestUrl La dirección URL no era válida. La solicitud debe ser similar a /tenantdomainname/Entity o /$metadata. El nombre de dominio del inquilino puede ser cualquiera de los nombres de dominio comprobado o sin comprobar o el identificador de contexto.
400 Request_UnsupportedQuery No se admite la solicitud GET. Corrija los parámetros de solicitud y vuelva a intentarlo.
401 Authentication_ExpiredToken El token de acceso expiró. Renueve el token antes de enviar la solicitud. El token de acceso expiró. Renueve el token y vuelva a enviarlo.
401 Authentication_MissingOrMalformed Falta el token de acceso o tiene un formato incorrecto. El valor de access_token del encabezado de autorización falta o tiene un formato incorrecto. Este valor es obligatorio. Utilice el valor del token de autenticación.
401 Authorization_IdentityDisabled La entidad de seguridad de la aplicación que realiza la llamada está deshabilitada. La entidad de seguridad especificada en el token de acceso está en el directorio, pero está deshabilitada. Vuelva a habilitar la cuenta en el directorio e inténtelo de nuevo.
401 Authorization_IdentityNotFound No se pudo establecer la identidad de la aplicación que realiza la llamada. La entidad de seguridad especificada en el token de acceso no se encuentra en el directorio. Esto puede ocurrir porque el token está obsoleto, la entidad de seguridad se ha eliminado del directorio o se ha retrasado la sincronización de directorios.
403 Authentication_Unauthorized Solicitud no autorizada. El token contiene notificaciones no válidas o no admitidas. Obtenga de nuevo el token de solicitud y vuelva a intentar la solicitud.
403 Authorization_RequestDenied Las credenciales especificadas no tiene suficientes privilegios para realizar esta solicitud. La solicitud se deniega debido a privilegios suficientes. Por ejemplo, una entidad de seguridad no- administrativa no tiene permiso para eliminar un recurso.
403 Directory_QuotaExceeded Se ha superado el límite de cuota del objeto de directorio para {tenantName}. Pida al administrador que aumente el límite de cuota o elimine objetos para reducir la cuota utilizada. Se ha superado una cuota de directorio. Puede que inquilino tenga demasiados objetos o que los objetos tengan demasiados valores. Esto también ocurre cuando se crean demasiados objetos en la entidad. Aumente la cantidad máxima de objetos permitidos en el inquilino o la entidad, o bien disminuya la cantidad de los valores que se incluyen en la solicitud de creación o actualización.
404 Directory_ObjectNotFound No se puede leer la información de la compañía del directorio.
404 Request_ResourceNotFound El recurso {recurso} no existe o uno de sus objetos consultados de propiedad de referencia no está presente. El recurso identificado por el URI no existe. Revise el valor y reintente la solicitud.
409 Request_MultipleObjectsWithSameKeyValue Se esperaba un único recurso para el resultado, pero se encontraron varios recursos. Actualice los objetos para resolver el conflicto. Este error puede producirse cuando hay dos o más objetos que tienen el mismo valor de clave, por ejemplo, cuando dos usuarios tienen el mismo UserPrincipalName.
429 Demasiadas solicitudes Este error se produce cuando las solicitudes se están limitando. Se devuelve un tiempo de espera sugerido en el valor Retry-After del encabezado de respuesta. Después de esperar el número recomendado de segundos, vuelva a intentarlo.
500 Service_InternalServerError El servidor detectó un error interno. Error interno del servidor al procesar la solicitud.
502 [Todo] “... Servicio no disponible..." Un servidor que actúa como puerta de enlace o proxy encontró un error de otro servidor al procesar la solicitud. Espere unos minutos y reintente la solicitud.
503 Directory_ConcurrencyViolation Error debido a que se realizan solicitudes simultáneas con el inquilino. Espere brevemente e inténtelo de nuevo.
503 Error durante la comprobación de DNS (Nota: Puede deberse a varias razones, por ejemplo, a que el DNS esté inactivo actualmente).
Authentication_Unknown Error interno del servidor. Este código de error se utiliza cuando no se aplican otros códigos de error.
Authentication_UnsupportedTokenType El tipo de token presentado no está controlado. Solo se admiten tokens de portador. El tipo de token no se admite. Revise el tipo de token antes de intentar la solicitud de nuevo.
Directory_BindingRedirection La información de inquilino no está disponible localmente. Utilice las direcciones URL siguientes para obtener la información. Cuando la partición del inquilino no está disponible en el centro de datos, los clientes deben conectarse al URI devuelto en la respuesta.
Directory_BindingRedirectionInternalServerError La información de inquilino no está disponible localmente. El servidor detectó un error interno al intentar rellenar los extremos del centro de datos más cercano. Cuando se produce una excepción de redirección de enlace, se rellena la lista de extremos del centro de datos más cercano para el servicio. Este error indica una excepción al rellenar la lista. Intente de nuevo la consulta.
Directory_CompanyNotFound No se puede leer la información de la compañía del directorio. Error al cargar la información de la compañía del servicio de directorio.
Directory_ReplicaUnavailable La réplica preferida no está disponible. Inténtelo de nuevo sin ningún encabezado de clave de sesión de réplica. Omita el encabezado x-ms-replica-session-key y vuelva a intentarlo.
Headers_DataContractVersionMissing Falta el encabezado de versión del contrato de datos. Incluya x-ms-dirapi-data-contract-version en la solicitud. Falta la versión del contrato del cliente en la solicitud.
Headers_HeaderNotSupported No se admite actualmente el encabezado {0}. La solicitud contiene un encabezado HTTP no admitido. Cambie el encabezado e intente de nuevo la solicitud.
Request_InvalidReplicaSessionKey La clave de sesión de réplica proporcionada no es válida. Corrija la clave de sesión de réplica e intente de nuevo la solicitud.
Request_ThrottledPermanently La solicitud está limitada permanentemente. Llame al servicio técnico para solucionar el problema. El inquilino ha superado de forma repetida y persistente el límite de tasa de solicitud de tokens. Las solicitudes del inquilino se rechazarán hasta que se renegocie el servicio. Para obtener Ayuda, póngase en contacto con el soporte técnico de Microsoft.

Recursos adicionales