> ## Documentation Index
> Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Understanding API error codes and responses

<Info>
  This comprehensive reference covers all error codes returned by the APIs. Each error includes a description, common causes, and resolution steps.
</Info>

## Error Response Format

All API errors follow a consistent JSON structure:

```json theme={null}
{
  "code": 400,
  "error": "InvalidToken",
  "description": "Jwt token is invalid."
}
```

**Fields:**

* `code` (number): HTTP status code
* `error` (string): Error identifier/type
* `description` (string): Human-readable error description

## Error Categories

<Tabs>
  <Tab title="Authentication">
    ### Authentication Errors

    <AccordionGroup>
      <Accordion title="ErrorUnauthorized">
        **HTTP Status**: 401

        **Description**: Invalid or missing authentication token

        **Common Causes**:

        * Missing `x-firmly-authorization` header
        * Expired authentication token
        * Invalid token format

        **Resolution**:

        * Ensure the authorization header is included
        * Check token expiration and refresh if needed
        * Verify token format matches expected pattern

        ```javascript theme={null}
        // Correct header format
        headers: {
          'x-firmly-authorization': 'Bearer your-token-here'
        }
        ```
      </Accordion>

      <Accordion title="MissingAuthHeader">
        **HTTP Status**: 401

        **Description**: Authorization header not provided

        **Common Causes**:

        * Header name typo
        * Header not included in request

        **Resolution**:

        * Add the `x-firmly-authorization` header
        * Check for typos in header name
      </Accordion>

      <Accordion title="ErrorInvalidSession">
        **HTTP Status**: 401

        **Description**: Session has expired or is invalid

        **Common Causes**:

        * Session timeout
        * Session transferred to another device
        * Invalid session ID

        **Resolution**:

        * Create a new session
        * Re-authenticate the user
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Cart Operations">
    ### Cart Operation Errors

    <AccordionGroup>
      <Accordion title="ErrorCartNotFound">
        **HTTP Status**: 404

        **Description**: Cart does not exist for the specified domain

        **Common Causes**:

        * Cart ID doesn't exist
        * Wrong domain specified
        * Cart has expired

        **Resolution**:

        * Verify the cart ID and domain
        * Create a new cart if needed
        * Check cart expiration settings
      </Accordion>

      <Accordion title="ErrorNoLineItem">
        **HTTP Status**: 400

        **Description**: Cart is empty or has no line items

        **Common Causes**:

        * Attempting operations on empty cart
        * All items have been removed
        * Cart cleared but not populated

        **Resolution**:

        * Add items to cart before proceeding
        * Check if items were accidentally cleared
        * Validate cart state before operations
      </Accordion>

      <Accordion title="ErrorLineItemNotFound">
        **HTTP Status**: 404

        **Description**: Specified line item not found in cart

        **Common Causes**:

        * Invalid line item ID
        * Item already removed
        * Wrong cart context

        **Resolution**:

        * Refresh cart to get current line item IDs
        * Verify line item exists before updating
        * Use correct line item ID from cart response
      </Accordion>

      <Accordion title="ErrorInvalidQuantity">
        **HTTP Status**: 400

        **Description**: Invalid quantity specified

        **Common Causes**:

        * Negative quantity
        * Zero quantity (use remove instead)
        * Exceeds maximum allowed

        **Resolution**:

        * Use positive integers for quantity
        * Set quantity to 0 to remove item
        * Check merchant quantity limits
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Product & Inventory">
    ### Product and Inventory Errors

    <AccordionGroup>
      <Accordion title="ErrorProductNotFound">
        **HTTP Status**: 404

        **Description**: Product or variant not found

        **Common Causes**:

        * Invalid variant ID
        * Product no longer available
        * Wrong product/variant reference

        **Resolution**:

        * Verify variant ID is correct
        * Check if product is still active
        * Use product search to find correct ID
      </Accordion>

      <Accordion title="ErrorProductNotSupported">
        **HTTP Status**: 400

        **Description**: Product cannot be added to cart

        **Common Causes**:

        * Product type restrictions
        * Regional availability
        * Business rules preventing addition

        **Resolution**:

        * Check product eligibility rules
        * Verify customer location
        * Contact support for restrictions
      </Accordion>

      <Accordion title="ErrorNotEnoughStock">
        **HTTP Status**: 400

        **Description**: Insufficient inventory available

        **Common Causes**:

        * Requested quantity exceeds stock
        * Stock depleted during checkout
        * Reserved inventory limits

        **Resolution**:

        * Reduce quantity to available stock
        * Check real-time inventory levels
        * Enable back-order if supported
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Shipment & Fulfillment">
    ### Shipment and Fulfillment Errors

    <AccordionGroup>
      <Accordion title="ErrorShipmentNotFound">
        **HTTP Status**: 404

        **Description**: Specified shipment not found

        **Common Causes**:

        * Invalid shipment ID
        * Shipment removed or consolidated
        * Wrong cart context

        **Resolution**:

        * Get current cart to refresh shipment IDs
        * Verify shipment ID before operations
        * Check if shipments were reorganized

        ```json theme={null}
        {
          "code": 404,
          "error": "ErrorShipmentNotFound",
          "description": "Shipment not found"
        }
        ```
      </Accordion>

      <Accordion title="ErrorInvalidFulfillmentType">
        **HTTP Status**: 400

        **Description**: Invalid or unsupported fulfillment type

        **Common Causes**:

        * Type not available for items
        * Invalid enum value
        * Merchant doesn't support type

        **Resolution**:

        * Check available fulfillment types
        * Use valid enum values only
        * Verify merchant configuration
      </Accordion>

      <Accordion title="ErrorShippingNotNeeded">
        **HTTP Status**: 400

        **Description**: Shipping not required for cart

        **Common Causes**:

        * Digital-only products
        * All items use pickup
        * No physical items in cart

        **Resolution**:

        * Skip shipping configuration
        * Check product types
        * Proceed to billing only
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Checkout & Address">
    ### Checkout and Address Errors

    <AccordionGroup>
      <Accordion title="ErrorCountryNotSupported">
        **HTTP Status**: 400

        **Description**: Country not supported by merchant

        **Common Causes**:

        * Shipping restrictions
        * Invalid country code
        * Regional limitations

        **Resolution**:

        * Use supported country codes
        * Check merchant shipping zones
        * Verify country format (ISO 3166)
      </Accordion>

      <Accordion title="ErrorInvalidState">
        **HTTP Status**: 400

        **Description**: Invalid state/province code

        **Common Causes**:

        * Wrong state code format
        * State doesn't match country
        * Invalid abbreviation

        **Resolution**:

        * Use standard state codes
        * Match state to selected country
        * Use full state name if needed
      </Accordion>

      <Accordion title="ErrorInvalidEmail">
        **HTTP Status**: 400

        **Description**: Invalid email format

        **Common Causes**:

        * Malformed email address
        * Missing @ symbol
        * Invalid domain

        **Resolution**:

        * Validate email format
        * Check for typos
        * Use standard email validation
      </Accordion>

      <Accordion title="ErrorInvalidShippingInfo">
        **HTTP Status**: 400

        **Description**: Shipping information validation failed

        **Common Causes**:

        * Missing required fields
        * Invalid postal code
        * Address validation failure

        **Resolution**:

        * Provide all required fields
        * Verify address format
        * Check postal code validity
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Promotions">
    ### Promotion and Discount Errors

    <AccordionGroup>
      <Accordion title="ErrorInvalidPromoCode">
        **HTTP Status**: 400

        **Description**: Promotional code is invalid or expired

        **Common Causes**:

        * Code doesn't exist
        * Code has expired
        * Already used (single-use codes)

        **Resolution**:

        * Verify code spelling
        * Check expiration date
        * Try alternative codes
      </Accordion>

      <Accordion title="ErrorPromoNotAvailable">
        **HTTP Status**: 400

        **Description**: Promo code not applicable to cart

        **Common Causes**:

        * Minimum purchase not met
        * Excluded products in cart
        * Customer not eligible

        **Resolution**:

        * Check promotion requirements
        * Verify cart meets conditions
        * Remove excluded items
      </Accordion>

      <Accordion title="ErrorClearPromoCodeNotAllowed">
        **HTTP Status**: 403

        **Description**: Merchant disabled promo code clearing

        **Common Causes**:

        * Business rule restriction
        * Promotional lock

        **Resolution**:

        * Contact merchant support
        * Create new cart if needed
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Addons">
    ### Addon Service Errors

    <AccordionGroup>
      <Accordion title="ErrorAddonNotFound">
        **HTTP Status**: 404

        **Description**: Addon not found or not available

        **Common Causes**:

        * Invalid addon ID
        * Addon no longer offered
        * Not eligible for cart items

        **Resolution**:

        * Get available addons from cart
        * Verify addon ID is current
        * Check addon eligibility rules
      </Accordion>

      <Accordion title="ErrorAddonNotApplicable">
        **HTTP Status**: 400

        **Description**: Addon cannot be applied to selected items

        **Common Causes**:

        * Wrong item selection
        * Incompatible product types
        * Exceeded addon limits

        **Resolution**:

        * Check addon scope rules
        * Verify item compatibility
        * Review addon constraints
      </Accordion>

      <Accordion title="ErrorAddonConflict">
        **HTTP Status**: 400

        **Description**: Addon conflicts with existing selections

        **Common Causes**:

        * Exclusive addon groups
        * Duplicate addon application
        * Constraint violations

        **Resolution**:

        * Remove conflicting addons
        * Check exclusive groups
        * Review addon rules
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Validation">
    ### Input Validation Errors

    <AccordionGroup>
      <Accordion title="ErrorBadRequest">
        **HTTP Status**: 400

        **Description**: General bad request error

        **Common Causes**:

        * Malformed JSON
        * Missing required parameters
        * Invalid data types

        **Resolution**:

        * Validate JSON syntax
        * Check API documentation
        * Ensure proper data types
      </Accordion>

      <Accordion title="ErrorInvalidInputBody">
        **HTTP Status**: 400

        **Description**: Request body validation failed

        **Common Causes**:

        * Schema validation failure
        * Missing required fields
        * Invalid field values

        **Resolution**:

        * Review request schema
        * Include all required fields
        * Validate field formats
      </Accordion>

      <Accordion title="ErrorUnprocessableEntity">
        **HTTP Status**: 422

        **Description**: Request understood but cannot be processed

        **Common Causes**:

        * Business logic violations
        * Invalid state transitions
        * Constraint failures

        **Resolution**:

        * Check business rules
        * Verify operation sequence
        * Review error details
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="System">
    ### System and Service Errors

    <AccordionGroup>
      <Accordion title="ErrorStoreUnavailable">
        **HTTP Status**: 503

        **Description**: Store service temporarily unavailable

        **Common Causes**:

        * Service maintenance
        * Temporary outage
        * Rate limiting

        **Resolution**:

        * Retry with exponential backoff
        * Check service status
        * Contact support if persistent
      </Accordion>

      <Accordion title="ErrorInternalServer">
        **HTTP Status**: 500

        **Description**: Internal server error occurred

        **Common Causes**:

        * Unexpected server issue
        * Database connectivity
        * Service dependencies

        **Resolution**:

        * Retry the request
        * Report to support with request ID
        * Check service status page
      </Accordion>

      <Accordion title="ErrorTimeout">
        **HTTP Status**: 504

        **Description**: Request timed out

        **Common Causes**:

        * Long-running operation
        * Network issues
        * Server overload

        **Resolution**:

        * Retry with smaller payload
        * Check network connectivity
        * Use pagination if available
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Quick Reference Table

| Error Code                 | HTTP Status | Category   | Quick Fix         |
| -------------------------- | ----------- | ---------- | ----------------- |
| `ErrorUnauthorized`        | 401         | Auth       | Check auth token  |
| `ErrorCartNotFound`        | 404         | Cart       | Verify cart ID    |
| `ErrorProductNotFound`     | 404         | Product    | Check variant ID  |
| `ErrorNotEnoughStock`      | 400         | Inventory  | Reduce quantity   |
| `ErrorInvalidPromoCode`    | 400         | Promo      | Verify code       |
| `ErrorCountryNotSupported` | 400         | Checkout   | Use valid country |
| `ErrorShipmentNotFound`    | 404         | Shipment   | Refresh cart      |
| `ErrorAddonNotFound`       | 404         | Addon      | Check addon ID    |
| `ErrorInvalidInputBody`    | 400         | Validation | Fix request body  |
| `ErrorStoreUnavailable`    | 503         | System     | Retry request     |

## Need Help?

If you encounter persistent errors or need assistance:

<CardGroup cols={2}>
  <Card title="API Status" icon="chart-simple" href="https://status.firmly.work">
    Check current service status
  </Card>

  <Card title="Support" icon="phone" href="mailto:support@firmly.com">
    Contact our support team
  </Card>
</CardGroup>