Catálogo de Errores

Trata el status HTTP como la señal primaria y confiable en este dominio; el code exacto puede variar de forma en distintos rincones de la superficie. Cuando dependas de un code específico, verifícalo contra el endpoint puntual — esta página documenta los que están confirmados por el código fuente, agrupados por de dónde vienen.

1. Errores tipados de la librería (@fenicia/products-service)

Estos son los errores que produce la capa de validación/repositorio de la librería subyacente, consumidos por lambda-products en las rutas de creación, actualización, borrado, variantes, medios, materiales y BOM.

ValidationError.fieldErrors trae un arreglo de errores por campo cuando la validación falla en más de un lugar a la vez (por ejemplo, un PUT con varios campos inválidos). La forma exacta de cada entrada de FieldError no fue verificada campo a campo en esta auditoría — asume al menos un campo field, pero confírmalo contra la respuesta real antes de parsearlo de forma estricta.

2. Errores de IA (AIServiceError)

Usados por Operaciones masivas en POST /products/bulk/ai/transform.

Cada AIServiceError trae un flag retryable: boolean — respétalo antes de reintentar automáticamente.

3. Catálogo de códigos declarados (no todos con clase propia)

La librería también declara estas constantes, aunque no todas tienen una clase de error dedicada como las de la sección 1:

ERROR_CODES:  VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, FORBIDDEN, INTERNAL_ERROR,
              DUPLICATE_SKU, INVALID_STATUS, INVALID_BINDING, QUOTA_EXCEEDED, SYNC_FAILED
 
HTTP_STATUS:  OK, CREATED, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
              CONFLICT, UNPROCESSABLE_ENTITY, INTERNAL_ERROR

4. Códigos inline por endpoint (namespace bad-request/…, forbidden/…, etc.)

Varias rutas de lambda-products arman su propio código como <categoría>/<detalle> directamente en el handler, sin pasar por la librería. Confirmados por área:

Consultas e inventario

Medios

CSV asíncrono (import/export)

Ver CSV masivo para el flujo completo de cada endpoint.

Operaciones masivas

5. Publicación a canal — convención SCREAMING_SNAKE_CASE

POST /products/export y rutas relacionadas de Publicación a canal usan una tercera convención, literales sin namespace de dos puntos ni de slash:

6. Categorización de marketplace — kebab-case sin namespace

POST /products/marketplace-categories valida exhaustivamente y devuelve uno de estos códigos (siempre 400):

invalid-skus · too-many-skus · invalid-sku-values · invalid-channel-id
invalid-category · invalid-category-path · category-id-too-long
category-name-too-long · category-path-too-deep

7. Lambda de categorías (/categories/...) — convención propia, distinta a todo lo anterior

Esta es una lambda separada (lambda-categories) y usa su propia convención, ya vista en la práctica como un único literal en mayúsculas sin namespace:

8. Errores de autenticación y autorización (genéricos, sin code de dominio confirmado)

Todas las rutas de este dominio devuelven 401 cuando falta un tenant resuelto y 403 cuando la API key no tiene el permiso RBAC requerido. A diferencia del catálogo anterior, esta auditoría no capturó un string de code específico y consistente para estos dos casos en Productos (el resto del dominio no comparte necesariamente el namespace auth:* que usan otros dominios de esta API) — trátalos por status HTTP, no por code, hasta que se confirme uno.

Cómo manejar esto en tu cliente

Dado que no hay un namespace único, la estrategia más segura es: ramifica primero por status HTTP, y usa el code solo dentro del endpoint puntual que estás llamando (donde ya sabes qué convención aplica).

const response = await fetch("https://api.fenicia.io/products/export", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.FENICIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channelId: "canal-shopify-mx" }),
});
 
const body = await response.json();
 
if (!response.ok) {
  // En este endpoint puntual, el code es SCREAMING_SNAKE_CASE (sección 5).
  if (body.code === "EXPORT_IN_PROGRESS") {
    // ya hay una exportación corriendo para este canal
  } else {
    console.error(response.status, body.code ?? body.error);
  }
}

Siguientes pasos

• API de Productos — visión general
• Modelo de datos
• Gestionar productos