Skip to content

Errors

The error object of the Store API, validation and rate limit errors, and every error code with its HTTP status and what the storefront should do.

Every error of the Store API, from a missing product to a payment provider outage, answers with an errors array and no data. Each error carries a code that does not change with the language of the request: branch on code in your storefront, and show detail to the customer.

Error Object

A request for a product that does not exist shows the shape that every error shares:

Request
curl "http://localhost:8000/store/products/classic-leather-boots" \
  -H "Accept: application/vnd.api+json"

The API answers 404 Not Found:

Response
{
    "errors": [
        {
            "status": "404",
            "code": "not_found",
            "title": "Not Found",
            "detail": "Not Found"
        }
    ]
}

Each error object has these members:

MemberTypeDescription
statusstringThe HTTP status code, as a string. Every error of one response has the status of the response.
codestringA code from Error Codes, or for a validation error the name of the rule that failed.
titlestringThe HTTP status text, such as Not Found, the same for every error with that status.
detailstringA message for the customer, in the language of the request.
source.pointerstringValidation errors only: the field the error is about, as described in Validation Errors.
metaobjectOnly on the codes that carry extra values, such as quantity_rule_violated.

The API answers in this format for every path under the /store prefix, with Content-Type: application/vnd.api+json. A URL that matches no route answers 404 not_found with a detail such as The route store/wishlists could not be found., and a route called with the wrong HTTP method answers 405 method_not_allowed with a detail that lists the methods the route accepts.

An unexpected exception answers 500 Internal Server Error with the server_error code and Internal Server Error as detail. The body never carries the exception message or a stack trace, even when APP_DEBUG is on: read the cause in the log of the Laravel application, storage/logs/laravel.log by default.

The detail follows the Accept-Language header, as described in Language. Messages that come from Laravel itself, such as validation messages, the login error and the password reset error, follow the language files of your application.

Validation Errors

A request whose body or query parameters fail validation answers 422 Unprocessable Content with one error object per message. Two fields that fail give two objects, and a field that fails two rules gives two objects with the same pointer. A login without a body fails on both fields:

Request
curl -X POST "http://localhost:8000/store/auth/login" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{}'

The API answers 422 Unprocessable Content:

Response
{
    "errors": [
        {
            "status": "422",
            "code": "required",
            "title": "Unprocessable Content",
            "detail": "The email field is required.",
            "source": {
                "pointer": "/data/attributes/email"
            }
        },
        {
            "status": "422",
            "code": "required",
            "title": "Unprocessable Content",
            "detail": "The password field is required.",
            "source": {
                "pointer": "/data/attributes/password"
            }
        }
    ]
}

The code of a validation error is one of these:

  • The name of the Laravel rule that failed, in snake case: required, email, unique, max. A rule object gives the snake case of its class name, such as image_file for File::image().
  • A code from Error Codes when Shopper raises the error itself, such as credentials_invalid or stock_insufficient.
  • invalid when no rule stands behind the message, such as an error your own route raises with ValidationException::withMessages().

Reading the Pointer

Request bodies are flat JSON, while source.pointer follows the JSON:API form /data/attributes/{field}. Remove the /data/attributes/ prefix to get the name of the field. A nested field keeps its path with / between the segments, so an error on lines.0.quantity points at /data/attributes/lines/0/quantity.

Errors on query parameters use the same form: an unknown currency in filter[currency] points at /data/attributes/filter/currency, and a forbidden include at /data/attributes/include.

A few codes point at a name that is not a field of the request. On POST /carts/{cartId}/complete and POST /carts/{cartId}/payment-session, which take no field, the pointer names the part of the cart that blocks the checkout: cart, email, promotion, shipping_method, payment_method or payment_session. Show these errors at the top of the checkout page instead of next to a field.

This function groups the messages of a validation error by field, ready for a form:

lib/store-api-errors.ts
type StoreApiError = {
    status: string;
    code: string;
    title: string;
    detail: string;
    source?: { pointer: string };
    meta?: Record<string, unknown>;
};

export function fieldErrors(errors: StoreApiError[]): Record<string, string[]> {
    const fields: Record<string, string[]> = {};

    for (const error of errors) {
        if (!error.source) {
            continue;
        }

        const field = error.source.pointer.replace('/data/attributes/', '').replaceAll('/', '.');

        (fields[field] ??= []).push(error.detail);
    }

    return fields;
}

Errors With Meta

Some errors carry a meta object with the values a storefront needs to fix the request. A quantity that breaks a quantity rule of its price answers quantity_rule_violated with the rule and the quantity that was sent:

Response
{
    "errors": [
        {
            "status": "422",
            "code": "quantity_rule_violated",
            "title": "Unprocessable Content",
            "detail": "This item must be ordered in multiples of 2.",
            "source": {
                "pointer": "/data/attributes/quantity"
            },
            "meta": {
                "purchasable_id": "01JD8YQ3H5K7M9P2R4T6V8X0Z1",
                "quantity": 3,
                "minimum": 2,
                "maximum": null,
                "increment": 2
            }
        }
    ]
}

minimum, maximum and increment are null when the rule does not set them. Use them to correct the quantity selector, as described in Cart.

Rate Limit Errors

A client that goes past a rate limiter, described in Rate Limits, gets 429 Too Many Requests with the rate_limited code until the limiter resets:

Response
{
    "errors": [
        {
            "status": "429",
            "code": "rate_limited",
            "title": "Too Many Requests",
            "detail": "Too Many Attempts."
        }
    ]
}

The response carries these headers:

HeaderValue
X-RateLimit-LimitThe number of requests the limiter allows per minute, such as 30 for shopper-api-checkout
X-RateLimit-Remaining0
Retry-AfterThe seconds to wait before the next request, such as 42
X-RateLimit-ResetThe Unix timestamp at which the limiter accepts requests again, such as 1795083912

Wait for Retry-After before sending the request again.

A login refused after too many failures, described in Failed Logins, also answers 429 with the rate_limited code, and a detail that gives the wait, such as Too many login attempts. Please try again in 59 seconds.. Its Retry-After header counts down the lockout of that email. The X-RateLimit-Limit and X-RateLimit-Remaining headers of that response describe the shopper-api-auth limiter of the route, not the lockout, so rely on Retry-After alone.

Error Codes

The codes below are every code the API sets itself, grouped by area. The Pointer column gives the end of source.pointer, after /data/attributes/, for the codes that answer as validation errors.

Four codes carry a Retry-After header and can succeed when the same request is sent again later: rate_limited, payment_session_in_progress, shipping_provider_unavailable and payment_provider_unavailable. Any other error answers the same until the request or the cart changes.

General Codes

These codes come from the HTTP status of the response, so any route can answer them:

CodeStatusPointerWhen it happensWhat to do
bad_request400An include, filter or sort name outside the allowlist of the endpoint. The detail lists the accepted namesFix the query, see Allowlists
unauthenticated401A route of the authenticated group called without a token, with an expired or revoked token, or with a token that lacks the store abilityDrop the stored token and send the customer to the login page, see Using the Token
forbidden403A download link asked for a file of an order that is not paid yet, or a cart transfer on a cart that belongs to another customerOffer the download once the order is paid. For a transfer, create a new cart
not_found404No record with this ID or slug for the request, or no route for the URL. A disabled or unpublished record, and a cart or an order of another customer, count as missingCheck the ID. For a cart the customer owned, see Using the Token
method_not_allowed405The route does not accept this HTTP method. The detail lists the methods it acceptsFix the method
conflict409POST /carts/{cartId}/payment-session on a cart that is already an orderRead the order instead of opening a session
invalid422Any fieldA validation error with no rule behind itShow the detail
rate_limited429Too many requests or too many failed logins, see Rate Limit ErrorsWait for Retry-After
server_error500 or higherAn unexpected exception on the serverRetry later. The cause is in the application log
http_errorAny otherAny other status, such as the 422 of GET /carts/{cartId}/shipping-options on a cart without a zone, which has no sourceFor a cart without a zone, set its zone_code, see Cart

Authentication

These codes come from the login and password reset endpoints described in Authentication:

CodeStatusPointerWhen it happensWhat to do
credentials_invalid422emailNo customer has this email, or the password is wrongShow one message for both cases. After 5 failures, the login locks for a minute
reset_token_invalid422emailThe reset token expired, was already used, or belongs to another emailOffer to send a new reset link

Query Parameters

These codes come from the query parameters described in JSON:API Conventions:

CodeStatusPointerWhen it happensWhat to do
include_not_allowed422includeAn include other than items on GET /orders/{orderId}, the order confirmation lookupAsk for items only, or read the order from the customer's account, see Orders
filter_too_wide422filter/{name}A filter with more than 50 comma-separated valuesSplit the request
currency_required422sort or filter/price_minGET /products sorted by price or filtered by price_min or price_max when no currency applies: no filter[currency], no zone, and no default currency on the shopSend filter[currency] or the X-Shopper-Zone header
currency_unknown422filter/currencyfilter[currency] names a currency that does not exist or is disabledSend a code listed by GET /currencies

Cart Lines and Prices

These codes come from adding and updating lines, changing the currency of a cart, and checking the cart out:

CodeStatusPointerWhen it happensWhat to do
purchasable_unavailable422purchasable_idNo product or variant with this ID can be bought: it does not exist, its product is not published, or the product is externalRefresh the product page
variant_required422purchasable_idThe ID is the one of a product sold through its variantsSend the ID of a variant, with purchasable_type set to variant
price_missing422purchasable_id, currency_code or cartThe product has no price in the cart currency: when the line is added, when the cart moves to another currency, or at checkoutRemove the line, or keep the cart in its currency
price_changed422cartAt checkout or when a payment session opens, the price of a line went up since it was added. The cart already holds the new prices; a lower price is applied without an errorShow the new total and ask the customer to confirm
stock_insufficient422quantity or cartNot enough stock for the quantity, when the line changes or at checkoutLower the quantity or remove the line
quantity_rule_violated422quantity or cartThe quantity breaks the minimum, maximum or increment of its price. The rule is in meta, see Errors With MetaCorrect the quantity

Cart State

These codes come from the state of the cart as a whole:

CodeStatusPointerWhen it happensWhat to do
cart_empty422cartCheckout of a cart without linesAdd a line
cart_completed409A change to a cart that is already an orderRead the order, and start a new cart
cart_line_locked409A change to a line whose price the merchant set by hand: a new quantity, the same product added again, or a new currency for the cartLeave the line as it is, or remove it
cart_line_metadata_conflict422metadataThe product is already in the cart with other metadataUpdate that line, or remove it first
cart_nothing_to_collect422cartA payment session on a cart whose total is zeroSet a manual payment method, which needs no session, and complete the cart
email_required422emailCheckout of a guest cart without an email. A customer's cart uses the email of the accountSet the email on the cart

Promotions

These codes come from applying a promotion code and from checking out a cart that has promotions:

CodeStatusPointerWhen it happensWhat to do
promotion_not_applicable422code or promotionThe code does not exist, is not active or does not apply to the cart. At checkout, a promotion of the cart that no longer applies. The detail never says why, so that codes cannot be guessedShow the detail. At checkout, show the new total
promotion_limit_reached422promotionAt checkout, a promotion of the cart reached its usage limitShow the new total
promotion_budget_reached422promotionAt checkout, the campaign of a promotion spent its budgetShow the new total

When checkout fails on a promotion, the API cancels the payment session of the cart and computes its totals again before it answers: show the new total, then open a new payment session.

Shipping

These codes come from choosing a shipping option and from checking out a cart that has products to ship:

CodeStatusPointerWhen it happensWhat to do
shipping_method_required422shipping_methodCheckout or a payment session on a cart with products to ship and no shipping optionSet a shipping method
shipping_option_unavailable422option_id or shipping_methodThe option is not among the options quoted for the cart, or no longer is at checkoutList the shipping options again and choose another one
shipping_price_changed422shipping_methodAt checkout, the carrier quotes the chosen option higher than when it was setSet the shipping method again to accept the new price
shipping_provider_unavailable503The carrier of the chosen option did not answerRetry after Retry-After (5 seconds)

Payment

These codes come from choosing a payment method, opening a payment session and completing the cart, described in Checkout:

CodeStatusPointerWhen it happensWhat to do
payment_method_required422payment_methodCheckout or a payment session on a cart without a payment methodSet a payment method
payment_method_unavailable422payment_method_idThe payment method is not offered for the cartChoose a method listed by GET /carts/{cartId}/payment-methods
payment_method_not_configured503The driver of the payment method has no configuration on the serverOffer another payment method
payment_provider_unavailable503The payment provider did not answer when the session opened, or when a change to the cart had to cancel the open paymentRetry after Retry-After (5 seconds)
payment_session_in_progress409Another request holds the payment session of the cart, such as a second click on the pay buttonRetry after Retry-After (3 seconds)
payment_session_collected409A change to the cart, or a new payment session, after the payment of the cart was collectedComplete the cart
payment_session_required422payment_sessionCheckout with a payment method that needs a session, before one was openedOpen a payment session
payment_session_mismatch422payment_sessionCheckout of a cart whose total changed since the payment session openedOpen a new payment session and pay again
payment_released422cartAt checkout, a product ran out of stock after the payment was collected. The payment is refunded and the session clearedUpdate the cart and pay again

Account

This code comes from the customer account endpoints described in Customers:

CodeStatusPointerWhen it happensWhat to do
avatar_invalid422avatarThe avatar upload passed validation but holds no fileSend the image as a multipart/form-data part named avatar

Errors From Your Own Routes

A route you add under the prefix, as described in Adding Your Own Routes, answers its errors in the same format. A failed $request->validate() gives one object per message with the rule as code, and abort(403, 'This wishlist is private.') gives forbidden with your message as detail.

To answer with a code of the table, throw the exceptions the API uses:

app/Http/Controllers/Store/WishlistController.php
use Shopper\Http\Enum\ErrorCode;
use Shopper\Http\Exceptions\ApiException;
use Shopper\Http\Exceptions\ApiValidationException;

throw new ApiException(409, ErrorCode::Conflict, 'This product is already in the wishlist.');

throw ApiValidationException::withCode(ErrorCode::PurchasableUnavailable, [
    'product_id' => 'This product cannot be added to a wishlist.',
]);

ApiValidationException::withCode() answers 422 with the field as pointer, and takes a meta array as its third argument. The codes come from the ErrorCode enum, so a storefront only ever meets the codes of this page.

Next Steps

The cart and checkout guides show where each of these codes comes up in the storefront flow.

Last updated on

Edit on GitHub