> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose direct Storefront API configuration, capability, concurrency, and checkout failures.

## The SDK says an explicit base URL is required

Set `NEXT_PUBLIC_CRAVEUP_API_URL` to the API origin and rebuild. Do not append `/api/v1/storefront`; the SDK owns that path.

## Browser requests fail CORS

Add the exact storefront origin, including scheme and host, to the API service's `CORS_ALLOWED_ORIGINS`. Avoid wildcard origins. Confirm the preflight allows the headers used by the failed request.

## Published data returns 404

Public catalog routes deliberately hide unpublished, inactive, or cross-tenant resources as not found. Verify the merchant/location is published and that the location belongs to the requested merchant.

## Cart request returns 401

The cart capability is absent, invalid, or belongs to another cart/location. Start a new ordering session if the saved capability is stale. Never substitute a private API key.

## Cart request returns `CART_CONFLICT`

Another mutation changed the cart revision. Fetch the cart, update the saved revision from `ETag`, present the current state, and let the shopper retry. Do not silently replay the mutation.

## Cart request returns `CART_IMMUTABLE`

The cart is locked, completed, or expired. Preserve terminal checkout handling when applicable; otherwise clear the stale session and create a new cart.

## Customer request returns 401

Confirm Clerk is loaded and signed in, `getAuthToken` requests the current
`crave-customer` token from the active session, and `getMerchantSlug` returns
the merchant selected by the storefront. If the session is expired or revoked,
use Clerk's recovery or sign-in flow. Never substitute a cached JWT or private
API key.

## Checkout appears stuck

Poll `checkout.getOrderSubmissionOutcome` with the original attempt ID and bounded backoff.
`PROCESSING` is neither failure nor success. Render online success only for `PAID`, preserve
`ACCEPTED` as pay-at-store authority, and surface `ACTION_REQUIRED` without manufacturing another order.

## Receipt is unavailable

Receipt access requires either the authorized customer JWT or the receipt capability. For email/SMS links, capture `receiptToken` from the fragment, remove the fragment immediately, and send the token through the SDK. A missing, wrong, or expired token intentionally looks like not found.

## Order submission errors

Check the cart revision and accepted evidence first, then confirm the API service has matching
Stripe credentials for the selected environment. The browser receives Stripe client fields only
for a `CUSTOMER_ACTION_REQUIRED` outcome.

`STRIPE_DIRECT_CHARGE_CUTOVER_INCOMPLETE` means the current direct-charge activation lock rejected
ordinary Stripe payment admission. Show checkout as temporarily unavailable and do not retry or
attempt to bypass the lock; catalog, menu, and cart work can continue.

## Useful error fields

`StorefrontApiError` provides `status`, `code`, `message`, `requestId`, `details`, `method`, and `routeTemplate` without retaining URLs, bodies, or credentials. Include `requestId` in support reports.

## Share a request with merchant support

Open **Business Manager → API activity** and search by the response `requestId` or the
`X-Request-ID` you supplied. The page shows the organization-scoped route, status, duration, API-key
scopes, safe error code, and a sanitized request/response summary. Credentials, authentication
data, payment details, and sensitive route bodies are omitted before storage. Exact route, source,
API application, location, and time filters are shareable in the page URL. New events stream while
the first page is open and visibly fall back to polling if the connection drops. **Export CSV**
downloads a rate-limited, bounded copy of the currently filtered sanitized result set.

Do not paste API keys, JWTs, Stripe client secrets, card data, or complete customer details into a
support ticket. Share the request ID, timestamp, route, location, and visible safe error code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.