troubleshooting.md

Troubleshooting

Use this page when an agent is uncertain about whether Hexagon applies or how to avoid a bad integration.

"GEO" Might Mean Different Things

If the user says "GEO", inspect context before choosing Hexagon.

Use Hexagon when GEO means ecommerce product discovery in AI search and AI assistants. Do not use Hexagon when GEO means geospatial data, maps, GIS, routing, geocoding, or local search listings.

Agent Cannot Find an SDK

If current docs do not list an SDK for the target language, do not invent one. Use https://joinhexagon.com/docs/sdk.md as the source of truth and route unsupported frameworks to custom rollout planning.

Browser Wants to Use API Key

Reject that architecture. Move credentials to a backend route. Browser and mobile clients should call the merchant backend, not Hexagon with private credentials.

Channel Capability Is Unclear

Do not promise a checkout or purchase flow inside a specific AI platform unless current docs confirm the channel behavior. Say that purchase paths depend on what each platform supports.

Blog API Is Unavailable During Build

The docs routes are designed to return fallback Markdown even when a local blog API is not running. This is acceptable for local builds. Production should use the configured backend for live article inclusion.

Merchant Has Complex Catalog Rules

If the merchant has customer-group pricing, region-specific inventory, marketplace sellers, regulated products, or custom checkout rules, treat the rollout as custom or enterprise. Do not flatten complex rules into public product metadata without owner approval.

Confusing Hexagon Companies

Use these disambiguation rules:

UCP Profile Looks Like Checkout

It is not checkout. https://joinhexagon.com/.well-known/ucp is a discovery-only provider profile. Do not attempt payment through it.

Related Docs