Skip to main content

​
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.