Respuestas de error de Microsoft Graph y tipos de recursos

Los errores en Microsoft Graph se devuelven usando los códigos de estado HTTP estándar, así como un objeto de respuesta de error JSON.

Códigos de estado HTTP

La siguiente tabla enumera y describe los códigos de estado HTTP que se pueden devolver.

Código de estado Mensaje de estado Descripción
400 Solicitud incorrecta (Bad Request) No se puede procesar la solicitud porque es incorrecta o tiene un formato no válido.
401 No autorizado (Unauthorized) La información de autenticación requerida no se encuentra o no es válida para el recurso.
403 Prohibido (Forbidden) Se denegó el acceso al recurso solicitado. Puede que el usuario no tenga permisos suficientes.

Importante: Si se aplican las directivas de acceso condicional a un recurso, puede que se devuelva un error HTTP 403; Forbidden error = insufficent_claims. Para obtener más información sobre Microsoft Graph y el acceso condicional vea Instrucciones para desarrolladores para Acceso condicional de Azure Active Directory
404 No encontrado (Not Found) El recurso solicitado no existe.
405 Método no permitido (Method Not Allowed) No se permite el método HTTP de la solicitud en el recurso.
406 No es aceptable (Not Acceptable) Este servicio no es compatible con el formato solicitado en el encabezado Accept.
409 Conflicto (Conflict) El estado actual entra en conflicto con lo que la solicitud espera. Por ejemplo, la carpeta principal especificada podría no existir.
410 Pasado (Gone) El recurso solicitado ya no está disponible en el servidor.
411 Longitud requerida (Length Required) Se requiere un encabezado Content-Length en la solicitud.
412 Error de condición previa (Precondition Failed) Una condición previa proporcionada en la solicitud (por ejemplo, un encabezado if-match) no coincide con el estado actual del recurso.
413 Entidad de solicitud demasiado grande (Request Entity Too Large) El tamaño de la solicitud supera el límite máximo.
415 Tipo de medio no compatible (Unsupported Media Type) El tipo de contenido de la solicitud es un formato que no es compatible con el servicio.
416 El rango solicitado no se cumple (Requested Range Not Satisfiable) El rango de bytes especificado no es válido o no está disponible.
422 Entidad no procesable (Unprocessable Entity) No se puede procesar la solicitud porque es semánticamente incorrecta.
423 Bloqueado El recurso al que está accediendo está bloqueado.
429 Demasiadas solicitudes (Too Many Requests) La aplicación del cliente se ha limitado y no debería intentar repetir la solicitud hasta haya transcurrido un periodo de tiempo.
500 Error interno del servidor (Internal Server Error) Se produjo un error interno del servidor al procesar la solicitud.
501 No implementado (Not Implemented) La característica solicitada no se implementó.
503 Servicio no disponible (Service Unavailable) El servicio no está disponible temporalmente por mantenimiento o está sobrecargado. Puede repetir la solicitud después de un retraso, la longitud de los cuales puede especificarse en un encabezado Retry-After.
504 Tiempo de espera de puerta de enlace (Gateway Timeout) El servidor, aunque actúa como un proxy, no recibió una respuesta a tiempo del servidor precedente al que necesitaba acceder para completar la solicitud. Puede producirse junto con 503.
507 Almacenamiento insuficiente (Insufficient Storage) Se ha alcanzado la cuota de almacenamiento máxima.
509 Ha superado el límite de ancho de banda (Bandwidth Limit Exceeded) Su aplicación se ha limitado por superar el extremo máximo de ancho de banda. Su aplicación puede reintentar la solicitud de nuevo cuando haya transcurrido más tiempo.

La respuesta de error es un solo objeto JSON que contiene una propiedad única denominada error. Este objeto incluye todos los detalles del error. Puede usar la información devuelta aquí en lugar o además del código de estado HTTP. A continuación se muestra un ejemplo de un cuerpo completo de error JSON.

{
  "error": {
    "code": "invalidRange",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "requestId": "request-id",
      "date": "date-time"
    }
  }
}

Tipo de recurso de error

El recurso de error se devuelve cuando se produce un error en el procesamiento de una solicitud.

Las respuestas de error siguen la definición en la especificación OData v4 de las respuestas de error.

Representación JSON

El recurso de error se compone de estos recursos:

{
  "error": { "@odata.type": "odata.error" }  
}

tipo de recurso de error OData

En la respuesta del error se encuentra un recurso de error que incluye las siguientes propiedades:

{
  "code": "string",
  "message": "string",
  "innererror": { "@odata.type": "odata.error" }
}
Nombre de la propiedad Valor Descripción
code cadenas Una cadena de código de error para el error que se ha producido
message cadenas Un mensaje preparado para el desarrollador sobre el error que se ha producido. No debe mostrarse al usuario directamente.
innererror error object Opcional. Objetos de error adicionales que pueden ser más específicos que el error de nivel superior.

Propiedad del código

La propiedad code contiene uno de los siguientes valores posibles. Sus aplicaciones deben estar preparadas para controlar cualquiera de estos errores.

Código Descripción
accessDenied El autor de la llamada no tiene permiso para realizar la acción.
activityLimitReached Se ha limitado la aplicación o el usuario.
extensionError El buzón es de ubicación local y el servidor de Exchange no es compatible con las solicitudes federadas de Microsoft Graph, o existe alguna directiva de la aplicación que impide que la aplicación tenga acceso al buzón de correo.
generalException Se ha producido un error no especificado.
invalidRange El rango de bytes especificado no es válido o no está disponible.
invalidRequest La solicitud es incorrecta o tiene un formato no válido.
itemNotFound No se pudo encontrar el recurso.
malwareDetected Se detectó malware en el recurso solicitado.
nameAlreadyExists El nombre del elemento especificado ya existe.
notAllowed El sistema no permite esta acción.
notSupported La solicitud no es compatible con el sistema.
resourceModified El recurso que está siendo actualizado ha cambiado desde que el autor de llamada lo leyó la última vez, normalmente un error de coincidencia eTag.
resyncRequired El token delta ya no es válido, y la aplicación debe restablecer el estado de sincronización.
serviceNotAvailable El servicio no está disponible. Intente la solicitud de nuevo tras un retraso. Puede haber un encabezado Retry-After.
syncStateNotFound No se encuentra la generación del estado de sincronización. El token delta expiró y los datos se deben sincronizar nuevamente.
quotaLimitReached El usuario ha alcanzado su límite de cuota.
no autenticado El autor de llamada no está autenticado.

El objeto innererror puede contener de forma recursiva más objetos innererror con códigos de error adicionales y más concretos. Al controlar un error, las aplicaciones deben recorrer todos los códigos de error disponibles y usar el más detallado que comprendan. Algunos de los códigos más detallados se enumeran en la parte inferior de esta página.

Para comprobar que un objeto de error es un error que está esperando, debe recorrer los objetos innererror, buscando los códigos de error que espera. Por ejemplo:

public bool IsError(string expectedErrorCode)
{
    OneDriveInnerError errorCode = this.Error;
    while (null != errorCode)
    {
        if (errorCode.Code == expectedErrorCode)
            return true;
        errorCode = errorCode.InnerError;
    }
    return false;
}

Para obtener un ejemplo que muestra cómo controlar correctamente los errores, vea Error Code Handling (Controlar códigos de error).

La propiedad message en la raíz contiene un mensaje de error destinado a que el desarrollador lo lea. Los mensajes de error no están localizados y no deberían mostrarse directamente al usuario. Al tratar los errores, el código no debería desconectarse de los valores message porque pueden cambiar en cualquier momento y, a menudo, contienen información dinámica específica de la solicitud de error. Solo debería codificar en los códigos de error que se devuelvan en las propiedades de code.

Códigos de error detallados

A continuación, se presentan algunos errores adicionales que su aplicación puede encontrarse dentro de los objetos innererror anidados. Las aplicaciones no están obligadas a controlarlos, pero pueden hacerlo si lo desean. El servicio puede agregar nuevos códigos de error o dejar de devolver los antiguos en cualquier momento, por lo que es importante que todas las aplicaciones puedan controlar los códigos de error básicos.

Código Descripción
accessRestricted Acceso restringido para el propietario del elemento.
cannotSnapshotTree No se pudo obtener ninguna instantánea delta coherente. Inténtelo de nuevo más tarde.
childItemCountExceeded Se ha alcanzado el límite máximo del número de elementos secundarios.
entityTagDoesNotMatch La ETag no coincide con el valor del elemento actual.
fragmentLengthMismatch El tamaño total declarado para este fragmento es distinto del de la sesión de carga.
fragmentOutOfOrder El fragmento cargado está fuera de servicio.
fragmentOverlap El fragmento cargado se superpone a los datos existentes.
invalidAcceptType Tipo de aceptación no válido.
invalidParameterFormat Formato de parámetro no válido.
invalidPath El nombre contiene caracteres no válidos.
invalidQueryOption Opción de consulta no válida.
invalidStartIndex Índice de inicio no válido.
lockMismatch El token de bloqueo no coincide con el bloqueo existente.
lockNotFoundOrAlreadyExpired Actualmente no hay ningún bloqueo no caducado en el elemento.
lockOwnerMismatch El Id. del propietario de bloqueo no coincide con el Id. proporcionado.
malformedEntityTag El encabezado ETag tiene un formato no válido. Las ETags deben ser cadenas entre comillas.
maxDocumentCountExceeded Se ha alcanzado el límite máximo del número de documentos.
maxFileSizeExceeded Tamaño máximo de archivo excedido.
maxFolderCountExceeded Se ha alcanzado el límite máximo del número de carpetas.
maxFragmentLengthExceeded Tamaño máximo de archivo excedido.
maxItemCountExceeded Se ha alcanzado el límite máximo de número de elementos.
maxQueryLengthExceeded Se ha superado la longitud de consulta máxima.
maxStreamSizeExceeded Se ha superado el tamaño máximo de secuencia.
parameterIsTooLong El parámetro supera la longitud máxima.
parameterIsTooSmall El parámetro es inferior al valor mínimo.
pathIsTooLong La ruta de acceso supera la longitud máxima.
pathTooDeep Se ha alcanzado el límite de profundidad de la jerarquía de carpetas.
propertyNotUpdateable No se puede actualizar la propiedad.
resyncApplyDifferences Es necesario volver a sincronizar. Reemplace cualquier elemento local con la versión del servidor (incluyendo eliminaciones) si está seguro de que el servicio estaba actualizado con sus cambios locales cuando lo sincronizó por última vez. Cargar cualquier cambio local que no conoce el servidor.
resyncRequired Es necesario volver a sincronizar.
resyncUploadDifferences Es necesario volver a sincronizar. Cargue cualquier elemento local que el servicio no devolvió y cargue cualquier archivo que difiera de la versión del servidor (manteniendo ambas copias si no está seguro de cuál está más actualizada).
serviceNotAvailable El servidor no puede procesar la solicitud actual.
serviceReadOnly El recurso es temporalmente de solo lectura.
throttledRequest Demasiadas solicitudes.
tooManyResultsRequested Demasiados resultados solicitados.
tooManyTermsInQuery Demasiados términos en la consulta.
totalAffectedItemCountExceeded No se permite la operación porque el número de elementos afectados supera el umbral.
truncationNotAllowed No se permite el truncamiento de datos.
uploadSessionFailed Error de la sesión de carga.
uploadSessionIncomplete Sesión de carga incompleta.
uploadSessionNotFound Sesión de carga no encontrada.
virusSuspicious Este documento es sospechoso y puede tener un virus.
zeroOrFewerResultsRequested Cero o menos resultados solicitados.