Error Catalog

Treat the HTTP status as the primary, reliable signal in this domain; the exact code can vary in shape across different corners of the surface. When you depend on a specific code, verify it against the specific endpoint — this page documents the ones confirmed by the source code, grouped by where they come from.

1. Typed library errors (@fenicia/products-service)

These are the errors produced by the underlying library's validation/repository layer, consumed by lambda-products in the creation, update, deletion, variants, media, materials, and BOM routes.

ValidationError.fieldErrors carries an array of per-field errors when validation fails in more than one place at once (for example, a PUT with several invalid fields). The exact shape of each FieldError entry was not verified field by field in this audit — assume at least a field field, but confirm it against a real response before parsing it strictly.

2. AI errors (AIServiceError)

Used by Bulk operations in POST /products/bulk/ai/transform.

Every AIServiceError carries a retryable: boolean flag — respect it before retrying automatically.

3. Catalog of declared codes (not all have their own class)

The library also declares these constants, though not all of them have a dedicated error class like the ones in section 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. Inline per-endpoint codes (namespace bad-request/…, forbidden/…, etc.)

Several lambda-products routes build their own code as <category>/<detail> directly in the handler, without going through the library. Confirmed by area:

Queries and inventory

Media

Async CSV (import/export)

See Bulk CSV for the full flow of each endpoint.

Bulk operations

5. Channel publishing — SCREAMING_SNAKE_CASE convention

POST /products/export and related routes from Channel publishing use a third convention, literals with no colon or slash namespace:

6. Marketplace categorization — kebab-case without a namespace

POST /products/marketplace-categories validates exhaustively and returns one of these codes (always 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. Categories lambda (/categories/...) — its own convention, different from all the above

This is a separate lambda (lambda-categories) and uses its own convention, so far only seen in practice as a single uppercase literal with no namespace:

8. Authentication and authorization errors (generic, no confirmed domain code)

Every route in this domain returns 401 when there's no resolved tenant and 403 when the API key lacks the required RBAC permission. Unlike the catalog above, this audit did not capture a specific and consistent code string for these two cases in Products (the rest of the domain does not necessarily share the auth:* namespace used by other domains of this API) — treat them by HTTP status, not by code, until one is confirmed.

How to handle this in your client

Since there is no single namespace, the safest strategy is: branch on HTTP status first, and use code only within the specific endpoint you're calling (where you already know which convention applies).

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) {
  // On this specific endpoint, the code is SCREAMING_SNAKE_CASE (section 5).
  if (body.code === "EXPORT_IN_PROGRESS") {
    // an export is already running for this channel
  } else {
    console.error(response.status, body.code ?? body.error);
  }
}

Next steps

• Products API — overview
• Data model
• Manage products