Códigos de error y control de errores | Conceptos de Graph API
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. |