> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craveup.com/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 login and OTP requests used the same `merchantSlug`, and that `getAuthToken` returns the current customer JWT. Clear the JWT and restart login when the session is expired or revoked.

## Checkout appears stuck

Poll `checkout.getOrderResult` with bounded backoff. `payment_pending` and `order_pending` are not failures or success. Render success only for `completed`; render the supplied code for `failed`. Surface timeouts rather than manufacturing an 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.

## PaymentIntent errors

Check cart revision first, then confirm the API service has matching provider credentials for the selected environment. The browser receives only the PaymentIntent client secret and Stripe publishable key.

## Useful error fields

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