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 los códigos de estado HTTP más frecuentes.

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 tanto en el cuerpo de la respuesta como en los encabezados de respuesta.

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 como se documenta en la especificación de api o actualice el registro de la aplicación Microsoft Entra.

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 solicitud se limitó. Microsoft Fabric devuelve un código de estado 429 por dos motivos distintos, cada uno identificado por un diferente errorCode en el cuerpo de la respuesta.

Causas principales comunes

Código de error Description Resolución
RequestBlocked La tasa de solicitudes superó los límites de limitación del servicio. Espere la duración especificada en el Retry-After encabezado antes de volver a intentarlo. Consulte Controlar la limitación de velocidad en la aplicación.
CapacityLimitExceeded El cómputo (unidades de capacidad) consumido en su capacidad superó los límites de la SKU de Fabric adquirida. Vuelva a intentar realizar la solicitud más tarde. Consulte Cómo gestionar la limitación de capacidad.

Limitación de velocidad (RequestBlocked)

Un RequestBlocked error indica que la tasa de solicitudes superó los límites de limitación del servicio.

  • 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 de velocidad, 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.

Control de la limitación de velocidad en la 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 limitación de velocidad

  • 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.

Límite de capacidad superado (CapacityLimitExceeded)

Un error CapacityLimitExceeded indica que el cómputo (unidades de capacidad) consumido por su capacidad superó los límites de la SKU de Fabric adquirida. A diferencia de la limitación de tasa, esta limitación no se debe al número de llamadas a la API que realiza un cliente específico; refleja la capacidad de proceso total consumida en todas las cargas de trabajo de la capacidad.

Cuerpo de la respuesta de ejemplo:

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Gestionar la limitación de capacidad

Dado que esta limitación depende de la capacidad de proceso total consumida por su capacidad, en lugar de la tasa de solicitudes individuales, el encabezado Retry-After no es aplicable, y es poco probable que reintentar de inmediato tenga éxito hasta que el uso de proceso de la capacidad vuelva a situarse dentro de sus límites. Las aplicaciones deben:

  • Vuelva a intentar la solicitud más adelante mediante una directiva de reintento limitada con retroceso exponencial.
  • Si el error persiste, considere ampliar vertical u horizontalmente la capacidad de Fabric.

Para obtener más información sobre las unidades de capacidad, las SKU y cómo se consume la capacidad de Fabric, consulte Planifique el tamaño de su capacidad.

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, atender las señales de limitación de velocidad y optimizar los patrones de solicitudes, puede crear aplicaciones resilientes.

Contenido relacionado

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

  • Last updated on