Solución de problemas de las API REST de Microsoft Fabric

Introducción

Este artículo le ayuda a comprender y solucionar errores comunes devueltos por las API rest de Microsoft Fabric. Explica el formato de error estándar que usa el servicio y proporciona instrucciones para resolver las respuestas de error HTTP que se encuentran con frecuencia.

Descripción de las respuestas de error de Microsoft Fabric

Cuando se produce un error al procesar una solicitud a la API REST de Microsoft Fabric, el servicio devuelve un objeto estándar ErrorResponse en el cuerpo de la respuesta.

Al solucionar problemas, siempre capture y registre el requestId, ya que identifica de forma única la solicitud y es necesario al ponerse en contacto con el soporte técnico de Microsoft. El identificador de solicitud está disponible en el cuerpo de la respuesta y como un encabezado de respuesta denominado requestId.

Importante

  • errorCode los valores son estables y basados en contratos.
  • El texto legible message puede cambiar con el tiempo y no se debe analizar mediante programación.

Esquema ErrorResponse

Nombre Tipo Description
errorCode string Identificador estable de la condición de error. Use este valor al implementar la lógica de control de errores.
message string Una descripción legible del error.
moreDetails ErrorResponseDetails[] Lista opcional de detalles de error adicionales.
relatedResource ErrorRelatedResource Información sobre el recurso asociado al error, si procede.
requestId string Identificador único de la solicitud con error. Incluya este valor al ponerse en contacto con el soporte técnico de Microsoft.

El esquema de ErrorResponseDetails

Proporciona contexto adicional para escenarios de error complejos.

Nombre Tipo Description
errorCode string Identificador estable que describe los detalles de error específicos.
message string Una explicación legible del detalle del error.
relatedResource ErrorRelatedResource Recurso asociado a este detalle de error específico.

Esquema de RecursoRelacionadoConError

Identifica el recurso implicado en el error.

Nombre Tipo Description
resourceId string Identificador del recurso implicado en el error.
resourceType string Tipo del recurso (por ejemplo, área de trabajo, elemento o capacidad).

Escenarios comunes de error HTTP

En las secciones siguientes se describen los códigos de estado HTTP comunes devueltos por las API REST de Microsoft Fabric, junto con las causas principales típicas y las resoluciones recomendadas.

LA API devuelve 401: no autorizado

Una respuesta 401 indica que se produjo un error en la solicitud durante la autenticación o la validación del token de acceso.

Causas principales comunes

Código de error Description Resolución
TokenExpired El token de acceso ha expirado. Adquiera un nuevo token de acceso y vuelva a intentar la solicitud.
InsufficientScopes El token de acceso no incluye los ámbitos necesarios. Actualice la aplicación para solicitar los ámbitos necesarios, tal como se documenta en la especificación de API, o actualice el registro de la aplicación microsoft Entra ID en Azure Portal.

LA API devuelve 403: Prohibido

Una respuesta 403 indica que el autor de la llamada está autenticado, pero no tiene permisos suficientes para realizar la operación solicitada en el recurso de destino.

Causas principales comunes

Código de error Description Resolución
InsufficientPrivileges El autor de la llamada no tiene los permisos necesarios para acceder al recurso. Pida a un administrador de recursos o área de trabajo que conceda permisos suficientes al usuario o a la entidad de servicio que llama.

LA API devuelve 404: no encontrado

Una respuesta 404 indica que un recurso solicitado o al que se hace referencia no existe o no es accesible para el autor de la llamada.

Nota

Las API individuales pueden definir códigos de error adicionales específicos de la API. Consulte siempre la especificación de api para obtener detalles autoritativos.

Causas principales comunes

Código de error Description Resolución
WorkspaceNotFound No se encontró el área de trabajo especificada. Compruebe que se proporcionó el identificador de objeto del área de trabajo correcto.
EntityNotFound No se encontró el recurso solicitado. Confirme que se proporcionó el identificador de recurso correcto. La entidad que falta se identifica en el relatedResource campo de la respuesta de error.

LA API devuelve 429: demasiadas solicitudes

Una respuesta 429 indica que la tasa de solicitudes superó los límites de limitación del servicio (normalmente con errorCode establecido en RequestBlocked).

  • La limitación se aplica por identidad del autor de la llamada.
  • Normalmente, los límites de velocidad se evalúan durante más de un minuto.

Información de tiempo de reintento

Cuando se produce la limitación, la información de reintento se proporciona en dos ubicaciones:

  • Cuerpo de la respuesta (message)
    Ejemplo:
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After Encabezado de respuesta HTTP
    Especifica el número de segundos que el cliente debe esperar antes de volver a intentarlo.

Siempre se debe preferir el Retry-After encabezado cuando se implemente la lógica de reintento.

Gestionar la limitación en su aplicación

Las aplicaciones deben:

  • Detectar respuestas HTTP 429.
  • Analice y respete el Retry-After encabezado.
  • Aplique una directiva de reintentos delimitada, como retroceso exponencial con vibración para escenarios a gran escala.
  • Evite bucles de reintento infinitos.

Reducir la probabilidad de restricción

  • Use operaciones masivas y por lotes cuando estén disponibles.
  • Se prefieren las API de lista en las solicitudes repetidas de recursos únicos.
  • Almacenar en caché los datos a los que se accede con frecuencia, especialmente los metadatos que cambian con poca frecuencia.
  • Evite las ráfagas de tráfico mediante la distribución uniforme de solicitudes a lo largo del tiempo.

Resumen

La creación de integraciones confiables con las API REST de Microsoft Fabric requiere un control de errores sólido y patrones de solicitud eficaces. Al comprender las respuestas de error, respetar las señales de limitación y optimizar el uso de la API, las aplicaciones pueden permanecer estables y con un rendimiento a gran escala.

Contenido relacionado

Para obtener preguntas adicionales o instrucciones de la comunidad, consulte Comunidad de Microsoft Fabric.

  • Last updated on