Hydrogen errors and upgrades

Common error codes

Code	Meaning	Action
HEADLESS_CREDENTIAL_INVALID	Server credential is invalid or rotated.	Replace the server secret with the active Studio credential.
STOREFRONT_TOKEN_EXPIRED	Browser token expired.	Refresh once through the server session route.
STOREFRONT_ORIGIN_FORBIDDEN	Exact browser origin is not enabled.	Add the full origin in Studio; no paths or wildcards.
CATALOG_PRODUCT_NOT_READY	Product or selected media cannot be resolved safely.	Verify Shopify GIDs and product configuration, then retry readiness.
IDEMPOTENCY_CONFLICT	One execution ID was reused with different input.	Reuse the original payload or create a new ID for a deliberate new run.
EXECUTION_IN_PROGRESS	The same execution is already running.	Disable duplicate submit and wait for the original response.
VTO_CAPACITY_BUSY	Generation capacity is temporarily full.	Honor retry guidance and let the customer retry deliberately.
VTO_EXECUTION_UNAVAILABLE	Generation service is temporarily unavailable.	Show a recoverable error and use bounded retry.

Integration-specific failures

useVtoSession must be used within a VtoProvider usually means the lazy chunk bundled another provider context or the hook rendered outside the provider.

A signed upload 403 usually means the browser changed a required header, content type, origin, or used an expired URL. Do not fall back from persist to no_store unless bootstrap explicitly says no_store.

Upgrade procedure

1. Review the package changelog and peer dependency range.
2. Upgrade @aabhastech/shopify-vto and the compatible @aabhastech/contracts together.
3. Run type checking, unit tests, and the package size check.
4. Smoke test eligibility, token refresh, new and saved photos, both storage modes, cart attribution, and analytics consent.
5. Deploy to a preview origin registered in Studio before production.