Respuestas de error#

Código HTTP	Significado	Acción recomendada
`400 Bad Request`	El cuerpo de la solicitud o los parámetros de consulta no son válidos.	Corrija la solicitud antes de reintentar.
`401 Unauthorized`	Faltan las credenciales, son inválidas, han expirado o no están activas.	Verifique los encabezados de autenticación o comuníquese con Ideal House.
`403 Forbidden`	El `shopId` solicitado no está asociado a las credenciales.	Use el Shop ID asignado a las credenciales.
`404 Not Found`	No hay ningún estado de importación ni producto coincidente disponible.	Verifique el Shop ID y el ID de producto o la SKU solicitados.
`409 Conflict`	Ya hay otro trabajo de importación activo para la tienda.	Espere a que finalice el trabajo de importación actual.
`429 Too Many Requests`	La tasa de solicitudes es demasiado alta.	Reintente con espera exponencial entre reintentos y jitter.
`500 Internal Server Error`	El servicio encontró un error inesperado.	Reintente con espera exponencial entre reintentos. Comuníquese con Ideal House si el error persiste.
`502 Bad Gateway` o `503 Service Unavailable`	La API no está disponible temporalmente.	Reintente con espera exponencial entre reintentos.

Un error de validación puede usar el siguiente formato:

json

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

El texto en message puede variar. Use el código de estado HTTP y los campos de respuesta documentados para la lógica del programa.

Orientación para reintentos y recuperación#

Consulte cada 2 a 5 segundos mientras un trabajo esté pending o running.
Para respuestas 429, 500, 502 y 503, use espera exponencial entre reintentos con jitter y establezca un límite máximo de reintentos.
No reintente automáticamente respuestas 400, 401 o 403 sin corregir la solicitud o las credenciales.
Después de 409, espere a que el trabajo activo alcance completed o failed.
Si un envío excede el tiempo de espera antes de recibir una respuesta, consulte el punto de estado antes de enviar el lote nuevamente.
Es seguro reintentar el mismo producto con la misma SKU porque las importaciones usan un comportamiento de crear-o-actualizar.
Después de un trabajo completado con fallas a nivel de elemento, envíe un nuevo lote que contenga solo los productos con fallas.
Después de un error a nivel de trabajo, los productos contados en successCount pueden ya haber sido actualizados. Volver a enviar el lote original con los mismos códigos de producto (SKU) es seguro.
Una eliminación puede ya haber surtido efecto incluso si la solicitud devuelve 503. Es seguro reintentar la misma solicitud de eliminación.

El punto de estado está destinado a rastrear el trabajo activo o más reciente, no un historial permanente de importaciones. Almacene el lote enviado, el jobId, las respuestas de estado y el resultado final en su propio sistema para reconciliación y soporte.

Lista de verificación para producción#

Almacene el Client Secret en un gestor de secretos o en un entorno de servidor protegido.
Use una SKU estable y única para cada producto.
No envíe más de 500 productos por solicitud.
Asegúrese de que las URLs de imagen sean accesibles públicamente y permanezcan disponibles durante el procesamiento.
Establezca processImages: true explícitamente solo cuando se necesite preprocesamiento de imágenes y se acepte el cargo de procesamiento de 1 crédito por imagen. De lo contrario, omítalo o establézcalo como false.
Habilite la división de imágenes de suelo en tablas individuales solo configurando tanto processImages como processFloorImages como true.
Proporcione name, imageUrl, productUrl, width, height y un productType admitido para cada producto.
Cuando se proporcione, establezca status como active, inactive, out_of_stock o invalid.
Envíe las dimensiones como valores positivos con una unidad admitida, u omita la unidad para usar pulgadas; los valores almacenados se normalizan a pulgadas.
Conserve el jobId devuelto y compárelo con las respuestas de estado posteriores.
Trate completed con failedCount > 0 como un éxito parcial.
Pagine a través de la lista de productos en lugar de solicitar un catálogo sin límite.
Proporcione exactamente uno de productId o sku para operaciones de eliminación.
Implemente reintentos acotados con espera exponencial entre reintentos y jitter.

Para credenciales, valores de incorporación, asignación de tipos de producto o problemas de integración persistentes, comuníquese con su representante de integración de Ideal House.