Skip to content
Bifröst OrbitDocs

Troubleshooting the APIs

The errors the storefront API, GraphQL and the MCP server answer with, what each one means and what to do about it.

Reference6 min read

Every error from the storefront API has the same shape. The message is written so you can show it to a shopper as it is:

JSON
{ "error": { "code": "conflict", "message": "Only 2 of Tind 2 tent are left" } }

Validation errors answer 422 with code invalid and add issues, one per field. GraphQL puts the same message in errors, with the code under extensions.code. See GraphQL for its own codes, such as query_too_deep.

Calls from the browser

403 "This website isn't allowed to use this shop's cart. Add it to the allowed websites in Commerce Orbit's shop settings."
Why
A cart, checkout or order call came from a website that isn't the shop's Website or under Allowed websites.
What to do
An Admin adds it under Settings, such as https://northwilds.com. Only the scheme, host and port count. Up to 20 can be listed.
A CORS error in the browser console, with no answer
Why
The same as above.
What to do
As above. Reading products works from any website.
A CORS error on a request with your own headers
Why
Only Content-Type, Authorization and X-Api-Key are allowed.
What to do
Leave out other headers.
403 "A key that reads drafts must stay on your server…"
Why
A com_sk_ key was sent from a browser on another website.
What to do
Call from your server, or use a com_pk_ key in the browser.

Keys and shops

402 subscription_inactive
Why
The Commerce Orbit trial or plan ended, so the shop is paused.
What to do
An owner chooses a plan under Billing in Orbit; everything answers again within a minute. Show your own "temporarily unavailable" message meanwhile.
404 "Shop was not found"
Why
The shop address in the URL doesn't exist, or changed.
What to do
Copy it from Settings, such as northwilds.
401 "This API key isn't valid for this organisation…"
Why
The key is wrong, or belongs to another shop.
What to do
Check the key under API keys.
401 "This API key has been revoked…" or "…has expired…"
Why
The key was revoked, or passed its expiry date.
What to do
Create a new key. A wrong key fails even on reads that need none.
401 "Send an API key, or name the shop with ?organisation=…"
Why
A GraphQL request with neither.
What to do
Add ?organisation=northwilds or a key.
404 "Product was not found"
Why
No active product with that address or id. Draft products need a com_sk_ key; archived ones are never returned.
What to do
Check the address, or the product's status.

Carts

404 "Cart was not found"
Why
The token is wrong, or belongs to another shop. Start a new cart.
409 "This cart has already been ordered. Start a new one."
Why
The cart became a paid order, or an order on invoice. Start a new cart.
A line you added is missing
Why
The variant id doesn't exist, or its product isn't active. Lines like that are dropped.
422 "Enter a valid email address", "Use the two-letter country code"
Why
A field is in the wrong format. issues lists each one.
discountProblem: "That code has expired" and similar
Why
The code doesn't apply. It doesn't stop checkout; the cart is priced without it.
problems: "Storm shell jacket has no price in SEK"
Why
The variant has no price in the cart's currency. Switch currency, or ask the shop to add the price.
problems: "Shipping has no price in SEK"
Why
The chosen shipping rate has no price in the cart's currency.
problems: "Only 2 of Tind 2 tent are left", "Tind 2 tent is sold out"
Why
Not enough stock.
problems: "Something in your cart is no longer for sale"
Why
A product was made a draft, archived or binned. Remove the line with lines.

Checkout

400 "Your cart is empty", "Add your email address", "Add your name"
Why
The cart is missing them.
400 "Choose how you'd like it delivered", "Add the delivery address"
Why
No shipping, or a delivery rate without shippingAddress.
400 "Choose card or invoice"
Why
method is something other than card or invoice.
409 with the first entry of problems
Why
Something in the cart stops checkout. Read the cart.
409 "This shop can't take card payments yet"
Why
The shop has no working Stripe connection, or its key lacks a permission. See Connect your Stripe account.
409 "The payment couldn't start: …"
Why
Stripe refused to create the payment, with Stripe's reason. Nothing was created.
409 "Paying by invoice is only for companies with an account"
Why
The cart's company is null, or its terms aren't invoice.
409 "Your account is on hold. Contact us to order on invoice."
Why
The company's MAM account is on stop. Card payment still works.

An order stays pending

After stripe.confirmPayment, read the order with its reference and email: it asks Stripe and marks the order paid if the payment went through. If nobody pays within the shop's stock reservation time, 15 minutes unless the shop changes it, the order is cancelled and its stock released. Don't call checkout again to retry a failed payment: let the shopper try again with the same clientSecret. See Checkout with Stripe.

Orders

400 "Add the email address the order was placed with"
Why
No ?email=.
404 "Order was not found"
Why
The reference doesn't exist, or the email doesn't match the order's. Capitals in the email don't matter.
409 "The receipt is ready once the payment has gone through"
Why
The PDF of an order still waiting for its card payment.

Rate limits

429 with "Too many tries. Wait a minute and try again." (GraphQL: "Too many requests…") means one address made too many requests in a short time. The limits are in the storefront API. If your server calls on behalf of many shoppers, all its calls share its address, so cache catalogue answers on your side.

The MCP server

401 "Connect the assistant to Commerce Orbit again"
Why
The token is missing, wrong or expired and couldn't be renewed. Connect again from the assistant.
403 "The person who connected this assistant no longer has Commerce Orbit in the organisation"
Why
Their access was removed in Orbit.
"Your Commerce Orbit role doesn't allow that. Ask an admin of your organisation."
Why
A Viewer used update_product_text. Editors and Admins can.
413 "The request is too large"
Why
The request is over 1 MB.
"An order with that reference was not found"
Why
get_order was given a reference that doesn't exist. Use list_orders to find it.

Something failed on our side

500 with server_error means Commerce Orbit couldn't answer. Try again in a moment. The status of every Orbit service is at docs.bifrostorbit.com/status.

Was this page helpful?

Read next

The storefront APIRead the shop, products and collections, build a cart, check out with Stripe or on invoice and show the order, from your own website. Endpoints, fields, CORS, caching and rate limits.Checkout with StripeTake payment on your own website with Stripe's Payment Element, using the client secret and publishable key from checkout, send the shopper to their order page, and know what happens when they never finish.GraphQLRead the shop, products and collections in one request, with the schema, examples, errors and limits. Carts and checkout stay in the storefront API.API keysCreate keys for the storefront API and GraphQL to preview draft products on your website and to see which website calls and how often. Reading works without one.The MCP serverConnect any MCP client to Commerce Orbit with OAuth sign-in, and the tools it gets for products, collections, orders and the shop's status.Connect your Stripe accountMake a restricted key in Stripe with exactly the access Commerce Orbit needs, paste it in, and know what happens if the key stops working.