Feed Troubleshooting

Pre-launch API. The concepts described here are settled, but the API shape is not: request and response fields, parameters and defaults can still change. Build against it, and talk to your Luigi's Box contact before you put an integration into production.

Most feed problems come from incomplete snapshots, unstable IDs, inconsistent field types, or a mapping that no longer matches the source file.

Common mistakes

Sending only changed records instead of the full current snapshot.
Changing source IDs between exports.
Using a product type other than the exact canonical value product.
Sending one field as different data types in different records.
Putting catalog values in XML attributes. Attributes are ignored; use elements.

My changes are not appearing

Confirm the feed URL is reachable using the access method agreed during onboarding.
Confirm the source file contains the changed records.
Return an accurate ETag or Last-Modified header and update its value whenever the content changes.
Serve the feed with gzip compression. Conditional-update metadata and gzip are strongly recommended for timely, near-real-time synchronization.

See Serving your feed for polling and conditional request behavior.

Far fewer products are indexed

Confirm the feed configuration and mapping still match the source:

XML must use the configured repeating record element, written exactly as in the file, namespace prefix included: g:item, not item.
A run that reads no records fails with no_items_parsed when the file contradicts the settings; error_message says what the file looks like.
JSON must contain records at the configured array path.
CSV must use the configured delimiter and header row.
Each record must map to non-empty @id, @type, and @title fields — a blank or null title is rejected — with @id in the form <type>/<value>.
Each record must stay under about 1 MB once mapped; a larger one is rejected.

IDs are rejected or analytics do not match

Product IDs must be type-prefixed, such as product/123.

Keep the source ID immutable.
Use the exact product type.
Ensure the source ID prefix matches the object type. The mapping does not repair a missing or mismatched prefix.
Ensure analytics events resolve to the same canonical product ID.
Do not rely on a URL as the identity unless that mapping was explicitly configured.

A large update is rejected

Check that the export completed successfully.
Check the record element, array path, and CSV delimiter.

Category references do not resolve

Canonical product category references must use typed IDs:

{
  "@category": ["category/cat-shoes"]
}

The referenced category is allowed to arrive later, so a temporarily dangling reference is not itself an ingest error. Check that:

the reference uses the category/ type prefix;
the source mapping produces the expected category ID.

A feed linking categories by name path links a reference only when its path names exactly one category. Check that:

the category and product mappings split on the same separator, written exactly as the feeds write it;
each path starts at the root and uses the category feed’s names: Home > TV, not TV;
no two categories share a path: Men > Shirts twice links neither;
the category feed’s recipe matches its paths — ancestors only, or ending with the category itself;
with paths naming ancestors only, no category title holds the separator: under /, nothing links to a category titled TV/Audio;
both feeds were resent in full after the mappings changed.

Text is broken or garbled

Export feeds as UTF-8.
In XML, entity-encode special characters or wrap text in CDATA.
Do not entity-encode text inside CDATA.