Error codes

Every error answers { "error": { "code", "message", "details"? } } with the HTTP status of the exception. The codes below are read from the exception sites in the code. A validation failure carries VALIDATION_ERROR with one entry per field in details.

Generic codes

Thrown by the framework or by an exception raised without an explicit code; the code follows the HTTP status.

• BAD_REQUEST: 400
• UNAUTHORIZED: 401
• FORBIDDEN: 403
• NOT_FOUND: 404
• CONFLICT: 409
• UNPROCESSABLE_ENTITY: 422
• RATE_LIMITED: 429
• INTERNAL_SERVER_ERROR: 500

Database codes

A Prisma error the filter maps before it reaches the client.

• Prisma P2002: CONFLICT, 409. A record with this value already exists.
• Prisma P2003: CONFLICT, 409. Cannot delete, record is still referenced by another entity.
• Prisma P2025: NOT_FOUND, 404. The requested record was not found.

Explicit codes

ADDRESS_ACCESS_DENIED

HTTP 403.

• Access denied
• Thrown in apps/api/src/modules/users/users.service.ts.

ADDRESS_DEFAULT_FLAG_REQUIRED

HTTP 400.

• At least one of isDefaultShipping or isDefaultBilling must be true
• Thrown in apps/api/src/modules/users/address-default-flag-required.exception.ts.

ADDRESS_NOT_FOUND

HTTP 404.

• Address not found
• Thrown in apps/api/src/modules/users/users.service.ts.

ASSET_INVALID

HTTP 400.

• One or more asset IDs are invalid
• Thrown in apps/api/src/modules/reviews/asset-invalid.exception.ts.

AUTH_PERMISSION_INSUFFICIENT

HTTP 403.

• Insufficient permissions
• Thrown in apps/api/src/modules/auth/auth-permission-insufficient.exception.ts.

AUTH_UNAUTHENTICATED

HTTP 401.

• Authentication required
• Thrown in apps/api/src/common/session-auth.guard.ts.

AUTH_USER_DEACTIVATED

HTTP 401.

• Account is deactivated
• Thrown in apps/api/src/common/session-auth.guard.ts.

BOT_DETECTED

HTTP 400.

• Request could not be completed.
• Thrown in apps/api/src/common/bot-protection/bot-protection.guard.ts.

CAMPAIGN_INVALID_COUPON

HTTP 400.

• Coupon ”${couponCode}” is not an active promotion.
• Thrown in apps/api/src/modules/campaigns/campaign.service.ts.

CAMPAIGN_NOT_EDITABLE

HTTP 409.

• A ${campaign.status} campaign cannot be edited.
• Thrown in apps/api/src/modules/campaigns/campaign.service.ts.

CAMPAIGN_NOT_SENDABLE

HTTP 409.

• A ${campaign.status} campaign cannot be sent.
• This campaign is already sending or sent.
• Thrown in apps/api/src/modules/campaigns/campaign.service.ts.

CAPTCHA_FAILED

HTTP 400.

• Captcha verification failed.
• Thrown in apps/api/src/common/bot-protection/bot-protection.guard.ts.

CAPTCHA_REQUIRED

HTTP 400.

• Captcha verification is required.
• Thrown in apps/api/src/common/bot-protection/bot-protection.guard.ts.

CART_EMPTY

HTTP 400.

• Cart is empty
• Thrown in apps/api/src/modules/cart/cart.service.ts.

CART_IDENTITY_REQUIRED

HTTP 400.

• Cart identity required (userId or sessionId)
• Thrown in apps/api/src/modules/cart/cart.service.ts.

CART_INSUFFICIENT_STOCK

HTTP 400.

• Insufficient stock for the requested quantity
• Thrown in apps/api/src/modules/cart/cart-insufficient-stock.exception.ts.

CART_ITEM_NOT_FOUND

HTTP 404.

• Cart item ”${itemId}” not found
• Thrown in apps/api/src/modules/cart/cart.service.ts.

CART_NOT_FOUND

HTTP 404.

• Cart not found
• Thrown in apps/api/src/modules/cart/cart.service.ts.

CART_VARIANT_NOT_FOUND

HTTP 404.

• Product variant not found or unavailable
• Thrown in apps/api/src/modules/cart/cart-variant-not-found.exception.ts.

CATEGORY_DESCENDANT_AS_PARENT

HTTP 409.

• Cannot set a descendant as parent
• Thrown in apps/api/src/modules/categories/categories.service.ts.

CATEGORY_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/categories/category-not-found.exception.ts.

CATEGORY_PARENT_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/categories/category-parent-not-found.exception.ts.

COUPON_INVALID

HTTP 400.

• Invalid coupon
• Thrown in apps/api/src/modules/promotions/coupon-invalid.exception.ts.

CUSTOMER_EMAIL_IN_USE

HTTP 409.

• Email already in use
• Thrown in apps/api/src/modules/users/users.service.ts.

CUSTOMER_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/users/customer-not-found.exception.ts.

GIFT_CARD_AMOUNT_INVALID

HTTP 400.

• Thrown in apps/api/src/modules/gift-cards/gift-card-amount-invalid.exception.ts.

GIFT_CARD_CODE_TAKEN

HTTP 400.

• Gift card code ”${code}” is already in use
• Thrown in apps/api/src/modules/gift-cards/gift-cards.service.ts.

GIFT_CARD_CURRENCY_NOT_ENABLED

HTTP 400.

• Currency ”${currency}” is not enabled for this store
• Thrown in apps/api/src/modules/gift-cards/gift-card-currency-not-enabled.exception.ts.

GIFT_CARD_DEACTIVATED

HTTP 400.

• Thrown in apps/api/src/modules/gift-cards/gift-card-deactivated.exception.ts.

GIFT_CARD_INSUFFICIENT_BALANCE

HTTP 400.

• Thrown in apps/api/src/modules/gift-cards/gift-card-insufficient-balance.exception.ts.

GIFT_CARD_INVALID

HTTP 400.

• Invalid or expired gift card
• Thrown in apps/api/src/modules/gift-cards/gift-card-invalid.exception.ts.

GIFT_CARD_NO_RECIPIENT

HTTP 400.

• Gift card has no recipient email on file
• Thrown in apps/api/src/modules/gift-cards/gift-cards.service.ts.

GIFT_CARD_NOT_FOUND

HTTP 404.

• Gift card ”${id}” not found
• Thrown in apps/api/src/modules/gift-cards/gift-card-not-found.exception.ts.

IDEMPOTENCY_KEY_CONFLICT

HTTP 409.

• X-Idempotency-Key was previously used with a different request body.
• Thrown in apps/api/src/common/exceptions/idempotency.exception.ts.

IDEMPOTENCY_KEY_FORBIDDEN

HTTP 403.

• X-Idempotency-Key was previously used by another caller.
• Thrown in apps/api/src/common/exceptions/idempotency.exception.ts.

IDEMPOTENCY_KEY_MALFORMED

HTTP 400.

• X-Idempotency-Key must be a UUID v4 string.
• Thrown in apps/api/src/common/exceptions/idempotency.exception.ts.

IDEMPOTENCY_KEY_REQUIRED

HTTP 400.

• X-Idempotency-Key header is required for this endpoint.
• Thrown in apps/api/src/common/exceptions/idempotency.exception.ts.

INVALID_UNSUBSCRIBE_TOKEN

HTTP 400.

• The unsubscribe link is invalid or has expired.
• Thrown in apps/api/src/modules/mail/unsubscribe.controller.ts.

INVALID_WEBHOOK_URL

HTTP 400.

• Webhook URL is not a valid URL
• Thrown in apps/api/src/modules/webhooks/webhooks.utils.ts.

INVENTORY_ADJUST_MODE

HTTP 400.

• Thrown in apps/api/src/modules/inventory/inventory-adjust-mode.exception.ts.

INVENTORY_SET_BELOW_RESERVED

HTTP 400.

• Cannot set stock to ${setTo}: ${reserved} unit(s) are already reserved
• Thrown in apps/api/src/modules/inventory/inventory-set-below-reserved.exception.ts.

INVENTORY_STOCK_CONFLICT

HTTP 409.

• Stock changed since this screen was opened
• Thrown in apps/api/src/modules/inventory/inventory-stock-conflict.exception.ts.

LICENSE_FILE_MISSING

HTTP 400.

• attach the license file as file
• Thrown in apps/api/src/modules/license/license.controller.ts.

LICENSE_FILE_NOT_CONFIGURED

HTTP 400.

• this engine has no ${LICENSE_FILE_ENV} path configured, so there is nowhere to install a license
• Thrown in apps/api/src/modules/license/license.service.ts.

LICENSE_REFUSED

HTTP 400.

• Thrown in apps/api/src/modules/license/license.service.ts.

LICENSE_WRITE_FAILED

HTTP 400.

• the license verified but could not be written (${code})
• Thrown in apps/api/src/modules/license/license.service.ts.

ORDER_ADDRESS_NOT_FOUND

HTTP 404.

• Address ”${addressId}” not found
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_CANCEL_INELIGIBLE

HTTP 409.

• Thrown in apps/api/src/modules/orders/order-cancel-ineligible.exception.ts.

ORDER_CANCEL_SHIPMENT_IN_TRANSIT

HTTP 409.

• This order has a shipment in transit and cannot be cancelled. Use the return flow instead.
• Thrown in apps/api/src/modules/orders/order-cancel-shipment-in-transit.exception.ts.

ORDER_CART_EMPTY

HTTP 400.

• Cart is empty
• Thrown in apps/api/src/modules/orders/order-cart-empty.exception.ts.

ORDER_CUSTOMER_NOT_FOUND

HTTP 400.

• Customer not found
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_EDIT_INSUFFICIENT_STOCK

HTTP 409.

• Thrown in apps/api/src/modules/orders/order-edit-insufficient-stock.exception.ts.

ORDER_EDIT_ITEM_NOT_FOUND

HTTP 404.

• Order item ”${removal.orderItemId}” not found
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_EDIT_VARIANT_NOT_FOUND

HTTP 404.

• Variant ”${addItem.variantId}” not found
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_GUEST_ADDRESS_REQUIRED

HTTP 400.

• A shipping address is required to check out as a guest
• Thrown in apps/api/src/modules/orders/order-guest-address-required.exception.ts.

ORDER_GUEST_CHECKOUT_DISABLED

HTTP 403.

• Guest checkout is not available
• Thrown in apps/api/src/modules/orders/order-guest-checkout-disabled.exception.ts.

ORDER_GUEST_EMAIL_REQUIRED

HTTP 400.

• A contact email is required to check out as a guest
• Thrown in apps/api/src/modules/orders/order-guest-email-required.exception.ts.

ORDER_GUEST_SESSION_REQUIRED

HTTP 400.

• A cart session is required to check out as a guest
• Thrown in apps/api/src/modules/orders/order-guest-session-required.exception.ts.

ORDER_IDEMPOTENCY_IN_PROGRESS

HTTP 409.

• Order creation already in progress for this idempotency key
• Thrown in apps/api/src/modules/orders/order-idempotency-in-flight.exception.ts.

ORDER_INSUFFICIENT_STOCK

HTTP 409.

• Thrown in apps/api/src/modules/orders/order-insufficient-stock.exception.ts.

ORDER_INVOICE_NOT_READY

HTTP 404.

• Invoice not yet generated
• Thrown in apps/api/src/modules/orders/order-invoice-not-ready.exception.ts.

ORDER_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/orders/order-not-found.exception.ts.

ORDER_NOT_YOURS

HTTP 403.

• Not your order
• Thrown in apps/api/src/modules/orders/order-not-yours.exception.ts.

ORDER_PAYMENT_METHOD_INVALID

HTTP 400.

• Thrown in apps/api/src/modules/orders/order-payment-method-invalid.exception.ts.

ORDER_PAYMENT_METHOD_UNAVAILABLE

HTTP 400.

• No payment method is available
• Thrown in apps/api/src/modules/orders/order-payment-method-unavailable.exception.ts.

ORDER_SHIPMENT_ITEM_NOT_IN_ORDER

HTTP 400.

• Item ”${si.orderItemId}” does not belong to this order
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_SHIPMENT_NOT_FOUND

HTTP 404.

• Shipment ”${shipmentId}” not found for order ”${orderId}”
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_SHIPMENT_ORDER_CLOSED

HTTP 409.

• Thrown in apps/api/src/modules/orders/order-shipment-order-closed.exception.ts.

ORDER_SHIPPING_ADDRESS_REQUIRED

HTTP 400.

• Shipping address is required
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_STATUS_TRANSITION_INVALID

HTTP 400.

• Cannot transition from ${order.status} to ${newStatus}
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_UNEDITABLE_STATUS

HTTP 400.

• Order in ${order.status} status cannot be edited
• Thrown in apps/api/src/modules/orders/orders.service.ts.

ORDER_VARIANT_NOT_FOUND

HTTP 400.

• Variant ”${item.variantId}” not found or unavailable
• Thrown in apps/api/src/modules/orders/orders.service.ts.

OWNER_GUARD_PUBLIC_CONFLICT

HTTP 403.

• @OwnerGuard route cannot also be @Public()
• Thrown in libs/shared/common/src/guards/owner-guard.exceptions.ts.

OWNER_GUARD_USER_MISSING

HTTP 401.

• Authenticated user required
• Thrown in libs/shared/common/src/guards/owner-guard.exceptions.ts.

PRODUCT_ALREADY_ARCHIVED

HTTP 409.

• Product is already archived
• Thrown in apps/api/src/modules/products/products.service.ts.

PRODUCT_ARCHIVED_NOT_FOUND

HTTP 404.

• Archived product not found
• Thrown in apps/api/src/modules/products/products.service.ts.

PRODUCT_ASSET_PRIMARY_CONFLICT

HTTP 400.

• Only one asset can be marked as primary
• Thrown in apps/api/src/modules/products/products.service.ts.

PRODUCT_ATTRIBUTE_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/products/product-attribute-not-found.exception.ts.

PRODUCT_ATTRIBUTE_VALUE_CODE_TAKEN

HTTP 409.

• Value code ”${code}” already exists in this attribute
• Thrown in apps/api/src/modules/products/product-attribute-value-code-taken.exception.ts.

PRODUCT_ATTRIBUTE_VALUE_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/products/product-attribute-value-not-found.exception.ts.

PRODUCT_CATEGORY_NOT_FOUND

HTTP 400.

• Thrown in apps/api/src/modules/products/product-category-not-found.exception.ts.

PRODUCT_FAQ_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/products/product-faq-not-found.exception.ts.

PRODUCT_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/products/product-not-found.exception.ts.

PRODUCT_SKU_TAKEN

HTTP 409.

• SKU ”${sku}” is already in use
• Thrown in apps/api/src/modules/products/product-sku-taken.exception.ts.

PRODUCT_SLUG_TAKEN

HTTP 409.

• Slug ”${slug}” is already taken
• Thrown in apps/api/src/modules/products/product-slug-taken.exception.ts.

PRODUCT_SPEC_DUPLICATE_KEY

HTTP 400.

• Specifications ${labels.map((l) => "${l}").join(’ and ’)} are the same specification
• Thrown in apps/api/src/modules/products/product-spec-duplicate-key.exception.ts.

PRODUCT_SPEC_EMPTY_KEY

HTTP 400.

• Thrown in apps/api/src/modules/products/product-spec-empty-key.exception.ts.

PRODUCT_TYPE_CODE_TAKEN

HTTP 409.

• Product type code ”${code}” already exists
• Thrown in apps/api/src/modules/products/product-type-code-taken.exception.ts.

PRODUCT_TYPE_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/products/product-type-not-found.exception.ts.

PRODUCT_VARIANT_LAST_ACTIVE

HTTP 409.

• Cannot delete the last active variant
• Thrown in apps/api/src/modules/products/products.service.ts.

PRODUCT_VARIANT_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/products/product-variant-not-found.exception.ts.

PROFILE_CURRENT_PASSWORD_INCORRECT

HTTP 401.

• Current password is incorrect
• Thrown in apps/api/src/modules/users/profile-current-password-incorrect.exception.ts.

PROFILE_CURRENT_PASSWORD_REQUIRED

HTTP 400.

• Current password is required to change email, phone, or password
• Thrown in apps/api/src/modules/users/profile-current-password-required.exception.ts.

PROFILE_EMAIL_IN_USE

HTTP 409.

• Email already in use
• Thrown in apps/api/src/modules/users/profile-email-in-use.exception.ts.

QUESTION_ALREADY_ANSWERED

HTTP 409.

• This question has already been answered
• Thrown in apps/api/src/modules/reviews/question-already-answered.exception.ts.

QUESTION_NOT_AVAILABLE_FOR_ANSWER

HTTP 400.

• This question is not available for answers
• Thrown in apps/api/src/modules/reviews/question-not-available.exception.ts.

REVIEW_DUPLICATE

HTTP 409.

• You have already submitted a review for this product
• Thrown in apps/api/src/modules/reviews/review-duplicate.exception.ts.

REVIEW_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/reviews/review-not-found.exception.ts.

REVIEW_NOT_OWNED

HTTP 403.

• Not your review
• Thrown in apps/api/src/modules/reviews/review-not-owned.exception.ts.

REVIEW_PRODUCT_NOT_FOUND

HTTP 404.

• Product ”${slug}” not found
• Thrown in apps/api/src/modules/reviews/review-product-not-found.exception.ts.

REVIEW_QUESTION_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/reviews/review-question-not-found.exception.ts.

REVIEW_VERIFIED_PURCHASE_REQUIRED

HTTP 400.

• A verified purchase is required to leave a review
• Thrown in apps/api/src/modules/reviews/review-eligibility.exception.ts.

ROLE_NAME_TAKEN

HTTP 409.

• Role name already exists
• Thrown in apps/api/src/modules/users/users.service.ts.

ROLE_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/users/role-not-found.exception.ts.

SEO_FOREIGN_URL

HTTP 400.

• url must be on the public storefront origin.
• Thrown in apps/api/src/modules/seo/seo-submit.exceptions.ts.

SEO_MULTIPLE_INSPECT_TARGETS

HTTP 400.

• Provide exactly one inspection target: url or productId — not both.
• Thrown in apps/api/src/modules/seo/seo-inspect.exceptions.ts.

SEO_MULTIPLE_TARGETS

HTTP 400.

• Provide exactly one submit target: url, productIds, or sitemap — not several.
• Thrown in apps/api/src/modules/seo/seo-submit.exceptions.ts.

SEO_NO_APPLICABLE_ENGINE

HTTP 400.

• None of the requested engines can be submitted to for this target type.
• Thrown in apps/api/src/modules/seo/seo-submit.exceptions.ts.

SEO_NO_INSPECT_TARGET

HTTP 400.

• An inspection target is required: one of url or productId.
• Thrown in apps/api/src/modules/seo/seo-inspect.exceptions.ts.

SEO_NO_TARGET

HTTP 400.

• A submit target is required: one of url, productIds, or sitemap.
• Thrown in apps/api/src/modules/seo/seo-submit.exceptions.ts.

SETTINGS_CURRENCY_CONFIG_INVALID

HTTP 400.

• currencyConfig must be an object with a code
• Thrown in apps/api/src/modules/settings/settings.service.ts.

SETTINGS_DEFAULT_LOCALE_UNSUPPORTED

HTTP 400.

• defaultLocale must be one of the supportedLocales
• Thrown in apps/api/src/modules/settings/settings.service.ts.

SETTINGS_KEY_READ_ONLY

HTTP 400.

• ${key} is written by the license verification, not through settings
• Thrown in apps/api/src/modules/settings/settings.service.ts.

SETTINGS_LOCALE_NOT_IN_CATALOGUE

HTTP 400.

• the engine ships no strings for ${foreign.join(’, ’)} (catalogue: ${LOCALE_CATALOGUE.join(’, ’)})
• Thrown in apps/api/src/modules/settings/settings.service.ts.

SETTINGS_MONEY_SEPARATORS_EQUAL

HTTP 400.

• decimalSeparator and thousandsSeparator must differ
• Thrown in apps/api/src/modules/settings/settings.service.ts.

SETTINGS_RTL_LOCALE_UNSUPPORTED

HTTP 400.

• rtlLocales must be a subset of supportedLocales (${outside.join(’, ’)})
• Thrown in apps/api/src/modules/settings/settings.service.ts.

SHIPPING_METHOD_INVALID

HTTP 400.

• Selected shipping method is not valid for this destination
• Thrown in apps/api/src/modules/shipping/shipping-method-invalid.exception.ts.

SHIPPING_UNAVAILABLE

HTTP 400.

• Shipping is not available for this destination
• Thrown in apps/api/src/modules/shipping/shipping-unavailable.exception.ts.

STAFF_EMAIL_IN_USE

HTTP 409.

• Email already registered
• Thrown in apps/api/src/modules/users/users.service.ts.

STAFF_NOT_FOUND

HTTP 404.

• Thrown in apps/api/src/modules/users/staff-not-found.exception.ts.

STAFF_SELF_DEACTIVATE_FORBIDDEN

HTTP 403.

• Cannot deactivate your own account
• Thrown in apps/api/src/modules/users/users.service.ts.

STAFF_SELF_MODIFY_FORBIDDEN

HTTP 403.

• Cannot modify your own staff record
• Thrown in apps/api/src/modules/users/users.service.ts.

TEST_SEND_EMAIL_ONLY

HTTP 400.

• Only email templates can be test-sent (this one is ”${template.channel}”)
• Thrown in apps/api/src/modules/notifications/notification-templates.service.ts.

TEST_SEND_NO_RECIPIENT

HTTP 400.

• Your account has no email on file.
• Your account has no email address to send a test to
• Thrown in apps/api/src/modules/campaigns/campaign.service.ts, apps/api/src/modules/notifications/notification-templates.service.ts.

UNKNOWN_TEMPLATE_TOKEN

HTTP 400.

• Template references undeclared variable(s): ${unknown.join(’, ’)}. Add them to the flow’s variables list or remove the token.
• Thrown in apps/api/src/modules/notifications/notification-templates.service.ts.

USER_CREDENTIAL_CHANGE_FORBIDDEN

HTTP 400.

• Cannot change credentials for this account type
• Thrown in apps/api/src/modules/users/users.service.ts.

USER_NOT_FOUND

HTTP 404.

• User not found
• Thrown in apps/api/src/modules/users/users.service.ts.

VALIDATION_ERROR

HTTP 400.

• Validation failed
• Thrown in apps/api/src/main.ts.

WEBHOOK_NOT_FOUND

HTTP 404.

• Webhook subscription not found
• Thrown in apps/api/src/modules/webhooks/webhooks.service.ts.

WEBHOOK_URL_INTERNAL_IP

HTTP 400.

• Webhook URL must not target internal or loopback addresses
• Thrown in apps/api/src/modules/webhooks/webhooks.utils.ts.

WEBHOOK_URL_NOT_HTTPS

HTTP 400.

• Webhook URL must use the HTTPS scheme
• Thrown in apps/api/src/modules/webhooks/webhooks.utils.ts.

WISHLIST_PRODUCT_NOT_FOUND

HTTP 404.

• Product ”${productId}” not found
• Thrown in apps/api/src/modules/wishlist/wishlist-product-not-found.exception.ts.