Errores

Toda respuesta de error de la API sigue la misma estructura. Esta página la documenta y enumera los códigos posibles.

Estructura del body

{
  "timestamp": "2026-05-06T10:15:00",
  "status": 400,
  "error": "Bad Request",
  "message": "externalId: External ID is required, price: Price must be positive",
  "path": "/api/plugin/shops/shop_abc/products/sync"
}

Campo	Tipo	Descripción
timestamp	string (ISO-8601)	Momento del error en el servidor
status	integer	Código HTTP (mismo que la respuesta)
error	string	Frase corta (Bad Request, Unauthorized, etc.)
message	string	Detalle legible. Para 400 validación de payload: lista campo: motivo separados por coma
path	string	Ruta de la petición

Códigos HTTP

Código	Significado	Acción cliente
400 Bad Request	Validación de payload (validación de payload)	Revisar message y corregir el campo señalado
401 Unauthorized	Falta o es inválida la cabecera de auth (X-Widget-Token o X-Shop-API-Key)	Volver a generar/rotar credenciales o revisar entorno
403 Forbidden	Origin mismatch, cross-tenant, role insuficiente	Revisar dominio configurado en la tienda y shopId
404 Not Found	Recurso inexistente (shop, producto, etc.)	Verificar el ID
409 Conflict	Estado del recurso incompatible (por ejemplo doble verify)	Ver mensaje
422 Unprocessable Entity	Error lógico (ej. parentExternalId no existe en el batch ni en BD)	Ajustar payload
429 Too Many Requests	Rate limit	Esperar Retry-After, ver Rate Limits
500 Internal Server Error	Error inesperado en backend	Reintentar con backoff; si persiste, Soporte con request id

Errores a nivel de campo (400)

Los errores de validación de payload se concatenan en el campo message, separados por comas, con el formato campo: motivo. Ejemplos reales:

externalId: External ID is required
name: Product name is required
price: Price must be positive
description: size must be between 0 and 5000
currency: size must be between 0 and 3
rating: must be less than or equal to 5.0
products: Must provide between 1 and 500 products per batch

Validaciones del request POST /api/plugin/shops/{shopId}/products/sync: cada producto debe cumplir el contrato del schema PluginProduct; el batch debe tener entre 1 y 500 productos.

Tabla de validaciones del producto

Campo	Validación	Mensaje
externalId	obligatorio	External ID is required
name	obligatorio, longitud limitada	Product name is required / size must be between 0 and 512
description	longitud limitada	size must be between 0 and 5000
price	obligatorio, valor mínimo	Price is required / Price must be positive
currency	longitud limitada	size must be between 0 and 3
url	obligatorio	Product URL is required
rating	rango numérico	must be greater than or equal to 0.0 / must be less than or equal to 5.0
reviewCount	mínimo	must be greater than or equal to 0
stockQuantity	mínimo	must be greater than or equal to 0
salePrice	mínimo	must be greater than or equal to 0.0

Errores parciales en sync (200 con errors[])

El endpoint POST /api/plugin/shops/{shopId}/products/sync puede devolver 200 OK con éxito parcial cuando algunos productos fallan validación lógica:

{
  "totalReceived": 50,
  "newProducts": 35,
  "updatedProducts": 12,
  "skipped": 0,
  "failed": 3,
  "errors": [
    {
      "externalId": "wc_prod_999",
      "reason": "parentExternalId 'wc_parent_x' not found"
    },
    {
      "externalId": "wc_prod_1000",
      "reason": "Currency code must be ISO 4217 (3 characters)"
    },
    {
      "externalId": "wc_prod_1001",
      "reason": "Image URL is not a valid HTTP/HTTPS URL"
    }
  ],
  "productsCount": 7847,
  "remainingProducts": 2153
}

Tu integración debe inspeccionar errors[] y reintentar sólo los productos fallidos tras corregir el payload.

Correlación con logs

Si reportas un incidente al equipo:

1. Captura el timestamp, path y message de la respuesta.
2. Si tu cliente HTTP genera un request id (header X-Request-ID), inclúyelo.
3. Anonimiza el payload (quita externalId reales si llevan información sensible) antes de enviarlo a Soporte.

Próximas lecturas

• Rate Limits — backoff y headers.
• Shop API Key — Origin y 403.
• Widget Token — TTL 24 h y 401.