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

# Qoo10 搜索

> 按商店的显示顺序返回 Qoo10 搜索结果中的商品。可用参数：sort、minPrice、maxPrice、page、brand。也可以用 url 读取店铺页面。每次搜索 0.5 积分。



## OpenAPI

````yaml POST /v1/commerce/qoo10/search
openapi: 3.1.0
info:
  title: querying.ai
  description: >-
    One API for every AI answer engine. Every task is asynchronous: submit, then
    collect the result via webhook or polling.
  version: 1.0.0
servers:
  - url: https://api.querying.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/commerce/qoo10/search:
    post:
      tags:
        - Commerce
      summary: Search Qoo10
      description: >-
        Searches Qoo10 and answers with the products the search shows, ranked as
        the store ranks them. It takes Qoo10's own options: `sort`, `minPrice`,
        `maxPrice`, `page`, `brand`. `POST /v1/async/task` takes the same search
        as `COMMERCE_SERP` with `payload.site` set to `qoo10`. The request waits
        for the task as `POST /v1/sync/task` does: up to 290 seconds or what
        `Prefer: wait` asks, then `202` with the task and `Location` while it
        still runs. A completed search costs 0.5 credits.
      operationId: commerceSearchQoo10
      parameters:
        - $ref: '#/components/parameters/PreferWait'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 500
                  pattern: \S
                  description: The search, 1-500 characters. Send query or url, not both.
                url:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: >-
                    A Qoo10 shop page (https://www.qoo10.jp/shop/{shop}) to read
                    in place of a search: every product the page shows, in page
                    order, up to limit. A listing takes only url and limit.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 200
                  default: 20
                  description: >-
                    Products to return, 1-40, default 20. With url: 1-200,
                    default 200.
                sort:
                  type: string
                  enum:
                    - relevance
                    - price_asc
                    - price_desc
                    - reviews
                    - newest
                  default: relevance
                  description: >-
                    The order of the results. relevance, the default, keeps
                    Qoo10's own order; price_asc ranks the lowest price first;
                    price_desc ranks the highest price first; reviews ranks the
                    most reviewed first; newest ranks the newest first. Qoo10's
                    price_desc starts with listings priced at 99,999,999 yen.
                minPrice:
                  type: number
                  minimum: 0
                  description: >-
                    Lowest price in JPY, in whole units: a fraction rounds
                    inward. Either bound works alone.
                maxPrice:
                  type: number
                  minimum: 0
                  description: >-
                    Highest price in JPY, in whole units: a fraction rounds
                    inward. Either bound works alone.
                page:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                  description: >-
                    The store's results page, 1-10. rank counts from 1 within
                    the page.
                brand:
                  type: string
                  pattern: ^[0-9]{1,10}$
                  description: >-
                    A Qoo10 brand number, such as 120962, as the brand's page
                    address carries it.
                idempotencyKey:
                  $ref: '#/components/schemas/CommerceIdempotencyKey'
                priority:
                  $ref: '#/components/schemas/CommercePriority'
                webhook:
                  $ref: '#/components/schemas/CommerceWebhook'
              oneOf:
                - required:
                    - query
                  not:
                    required:
                      - url
                  properties:
                    limit:
                      maximum: 40
                - required:
                    - url
                  not:
                    required:
                      - query
                  propertyNames:
                    enum:
                      - url
                      - limit
                      - idempotencyKey
                      - priority
                      - webhook
            examples:
              search:
                summary: A search in the store's own order
                value:
                  query: anua
                  limit: 3
              options:
                summary: A search with Qoo10's options
                value:
                  query: anua
                  sort: price_asc
                  minPrice: 1000
                  maxPrice: 3000
                  page: 2
                  brand: '120962'
                  limit: 10
              listing:
                summary: A Qoo10 shop's listing
                value:
                  url: https://www.qoo10.jp/shop/LG-DailyBeauty
                  limit: 100
      responses:
        '200':
          description: >-
            The search ended: the body `GET /v1/async/task/{id}` returns, with
            the products in `response` or the reason in `error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
              example:
                success: true
                task:
                  id: 8f2c1e40-0000-0000-0000-000000000000
                  taskType: COMMERCE_SERP
                  status: COMPLETED
                  priority: 1
                  createdAt: '2026-07-09T04:12:00.000Z'
                  latencyMs: 4210
                credits:
                  creditsToCharge: 0.5
                  creditsCharged: 0.5
                response:
                  site: qoo10
                  query: anua
                  country: JP
                  returnedCount: 3
                  products:
                    - rank: 1
                      productId: '1204422003'
                      title: >-
                        【NEW】Barrier Reboot
                        デイリーモイスチャライザー/ウォータージェルクリーム/インテンシブクリーム100ml
                      url: https://www.qoo10.jp/g/1204422003
                      price: 3400
                      currency: JPY
                      rating: 4.65
                      reviewCount: 10640
                      brand: アヌア
                      imageUrl: >-
                        https://gd.image-qoo10.jp/li/068/078/8542078068.g_100-w-st_g.jpg
                    - rank: 2
                      productId: '1114201571'
                      title: 【お守り美容液】PDRN ヒアルロン酸カプセル100 セラム 30ml / 50ml (単品/セット)
                      url: https://www.qoo10.jp/g/1114201571
                      price: 3200
                      currency: JPY
                      rating: 4.75
                      reviewCount: 73885
                      brand: アヌア
                      imageUrl: >-
                        https://gd.image-qoo10.jp/li/969/535/8545535969.g_100-w-st_g.jpg
                    - rank: 3
                      productId: '1103518685'
                      title: アゼライン酸15 インテンスカーミングセラム 30ml
                      url: https://www.qoo10.jp/g/1103518685
                      price: 2800
                      currency: JPY
                      rating: 4.65
                      reviewCount: 67999
                      brand: アヌア
                      imageUrl: >-
                        https://gd.image-qoo10.jp/li/306/080/8542080306.g_100-w-st_g.jpg
        '202':
          $ref: '#/components/responses/CommerceTaskRunning'
        '400':
          $ref: '#/components/responses/CommerceUnknownField'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/CommerceKeyScopeDenied'
        '409':
          $ref: '#/components/responses/IdempotencyKeyExpired'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '422':
          $ref: '#/components/responses/CommerceSearchInvalid'
        '429':
          $ref: '#/components/responses/TaskLimitExceeded'
        '503':
          $ref: '#/components/responses/CommerceUnavailable'
components:
  parameters:
    PreferWait:
      name: Prefer
      in: header
      required: false
      description: >-
        `wait=<seconds>` holds the request at most that long, up to 290.
        `wait=0` answers with the task id at once.
      schema:
        type: string
        example: wait=120
  schemas:
    CommerceIdempotencyKey:
      type: string
      description: >-
        Optional. A repeat of the key within at least 30 days answers with the
        task that holds it, so a caller that hung up can ask again.
    CommercePriority:
      type: integer
      description: >-
        Compatibility field; does not guarantee execution order. Values outside
        1–10 are clamped, not rejected.
      minimum: 1
      maximum: 10
      default: 1
    CommerceWebhook:
      type: object
      description: Optional. Omit to collect the result by polling instead.
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Receives a POST when the task reaches a terminal state.
    TaskResponse:
      type: object
      required:
        - success
        - task
        - credits
      allOf:
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: COMMERCE_SERP
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/CommerceSerpResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: COMMERCE_PRODUCT
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/CommerceProductResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: SOCIAL
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/SocialResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: ADS
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/AdsResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: GOOGLE_PLACES
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/GooglePlacesResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: GOOGLE_NEWS
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/GoogleNewsResult'
        - if:
            properties:
              task:
                properties:
                  taskType:
                    const: SEARCH
                required:
                  - taskType
            required:
              - task
          then:
            properties:
              response:
                $ref: '#/components/schemas/SearchResult'
      properties:
        success:
          type: boolean
          const: true
        task:
          $ref: '#/components/schemas/TaskMeta'
        credits:
          $ref: '#/components/schemas/Credits'
        response:
          type: object
          description: >-
            The engine-specific result. Absent until the task is terminal. See
            the Engines guide for per-engine shapes. NAVER_AI_TAB preserves the
            original text, markdown, sources and cards when Naver returns HTTP
            success, a valid stream ending in done, and nonempty answer text
            with unknown_error. It includes upstreamError and returns
            immediately without retrying or rephrasing, even with retryQuery.
            COMPLETED means collection finished; the answer may still be
            incomplete. Empty, cut-off or malformed streams still fail. Policy
            refusals complete with a policy_declined notice. rawContent is
            returned only with include.rawResponse. With
            `include.citationAnalysis`, answer results also carry
            `citationAnalysis` (see Include). CITATION_ANALYSIS returns
            CitationAnalysisResult; see the Citation Analysis guide.
            PROMPT_RESEARCH returns PromptResearchResult; see the Prompt
            Research guide. GEO_SCORE returns GeoScoreResult; see the GEO Score
            guide. Answer engines with `include.analysis` add `analysis`
            (AnswerAnalysis).
          properties:
            upstreamError:
              $ref: '#/components/schemas/NaverAiTabUpstreamError'
          additionalProperties: true
        error:
          type: string
          description: >-
            Present when `task.status` is `FAILED`. A plain string, not the
            `{code, message, timestamp}` object used by request-level errors.
    TaskMeta:
      type: object
      required:
        - id
        - taskType
        - status
        - priority
        - createdAt
        - latencyMs
      properties:
        id:
          type: string
          format: uuid
        taskType:
          $ref: '#/components/schemas/TaskResultType'
        status:
          $ref: '#/components/schemas/TaskStatus'
        priority:
          type: integer
        createdAt:
          type: string
          format: date-time
        latencyMs:
          type:
            - integer
            - 'null'
          description: >-
            Milliseconds from the worker's first pickup to the final outcome,
            excluding the queue wait. `null` until the task settles. Returned by
            polling, the webhook and the submit response alike.
        idempotencyKey:
          type: string
          description: >-
            Echoed back verbatim. **Omitted**, not null, when the caller
            supplied none.
    Credits:
      type: object
      description: >-
        Credits, with up to two decimals (for example `1.25`). The submit
        response always shows `0`: nothing is charged yet, and the task's price
        is held from your balance when it starts. Polling shows `0` until the
        task is terminal, then the settled charge: the task's price for
        COMPLETED, `0` for FAILED. A task webhook reports the same charge in
        `creditsCharged`; on a FAILED task it reports the task's price in
        `creditsToCharge` and `0` in `creditsCharged`. CITATION_ANALYSIS,
        GOOGLE_PLACES and GOOGLE_NEWS are charged by usage, up to the hold
        placed when the task starts.
      properties:
        creditsToCharge:
          type: number
        creditsCharged:
          type:
            - number
            - 'null'
    NaverAiTabUpstreamError:
      type: object
      description: >-
        Optional NAVER_AI_TAB generation error accompanying preserved answer
        text. Collection finished, but the answer may be incomplete.
      required:
        - type
      additionalProperties: false
      properties:
        type:
          type: string
          const: unknown_error
        message:
          type: string
          description: >-
            Naver's exact notice text, without translation or rewording. Omitted
            when Naver provides no notice text.
    AsyncResponse:
      type: object
      required:
        - success
        - task
        - credits
      properties:
        success:
          type: boolean
          const: true
        task:
          $ref: '#/components/schemas/TaskMeta'
        credits:
          $ref: '#/components/schemas/Credits'
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorDetail'
    TaskResultType:
      description: >-
        Task types returned by task polling, submissions, batch results and
        webhooks, including tasks created by dedicated endpoints. This is not a
        submission engine list.
      anyOf:
        - $ref: '#/components/schemas/TaskType'
        - type: string
          enum:
            - AI_RENDERING
    TaskStatus:
      type: string
      description: >-
        `PROCESSING` means a worker holds the task. `COMPLETED` and `FAILED` are
        terminal. For NAVER_AI_TAB with response.upstreamError, `COMPLETED`
        means collection finished; the answer may still be incomplete.
      enum:
        - QUEUED
        - PROCESSING
        - COMPLETED
        - FAILED
    ErrorDetail:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable, safe to branch on. See the Errors guide for the full list.
        message:
          type: string
          description: For humans. May change.
        details:
          description: >-
            Context for the error. An array of `{field, message}` on most
            `VALIDATION_ERROR`s; an object elsewhere (for example `{id}` on
            `RESOURCE_NOT_FOUND`, `retryAfterSec` on 429 and 503 codes). Omitted
            when there is nothing to add.
          oneOf:
            - type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
            - type: object
              additionalProperties: true
        timestamp:
          type: string
          format: date-time
    TaskType:
      type: string
      description: >-
        The engine to query. `NAVER` is a deprecated alias for `NAVER_AI_BRIEF`.
        GOOGLE_AIO and GOOGLE_AIMODE are the names of Google AI Overviews and
        Google AI Mode; the earlier names GOOGLE and AIMODE are accepted too,
        and a task answers under the name it was sent with. `NAVER_AI_MODE` is
        accepted as an earlier spelling of `NAVER_AI_TAB`. `BING_AIMODE` returns
        Bing AI Mode's answer (bing.com/copilotsearch) for `payload.query` in
        AE, AU, BR, CA, DE, EE, ES, FR, GB, HK, HU, IE, IN, IT, JP, MX, NL, PL,
        PT, RO, RS, SE, SG, SK, TR, US and ZA, and refuses other countries with
        422 REGION_UNSUPPORTED; `BING_COPILOT_SEARCH` and `COPILOT_SEARCH` are
        accepted as its other names. `BING_COPILOT` and `MICROSOFT_COPILOT` are
        accepted as other names of `COPILOT` (Microsoft Copilot). `GOOGLE_SERP`
        returns the Google results page without the AI Overview; `payload.page`
        selects pages 1-10. `BRAVE_SEARCH` returns Brave's own results page:
        organic results, ads, FAQ, knowledge panel, news, videos, discussions,
        places and related queries, with `payload.country` from Brave's markets
        and `payload.page` from 1 to 10; there is no HTML payload, so `include`
        adds nothing. `GOOGLE_PLACES` returns the places Google's Places tab
        lists for `payload.query`, up to 100 over up to five pages of 20, every
        page searched from `payload.city` or `payload.uule`; `payload.limit`
        (1-100, default 20) sets how many, and the task is charged 1 credit per
        page read (GooglePlacesResult). `NAVER_SERP` returns Naver's web
        results, 15 per page (`payload.page` 1-10), and with `payload.action`
        `page` reads one naver.com page by `payload.url`. `META_AI` returns the
        meta.ai chat answer with its cited sources, search queries and the
        products, places, photos and accounts it shows (`shoppingCards`,
        `inlineProducts`, `map`, `images`, `socialCards`); a prompt Meta refuses
        completes with an empty text and a `notice` quoting Meta. `QWEN` returns
        the answer of Qwen's China web chat (qianwen.com) with its web search,
        sources and search queries; `payload.country` sets the exit and the
        answer locale. `DOUBAO` returns the answer of Doubao's China web chat
        (doubao.com) with its web search, sources and search queries; it always
        asks from mainland China, whatever `payload.country` is. `BAIDU_WENXIN`
        returns the answer of Baidu's Wenxin web chat (文心, wenxin.baidu.com)
        with the pages it read as sources and its search queries; it always asks
        from mainland China, whatever `payload.country` is. `BAIDU_AI_SEARCH`
        returns the AI answer card at the top of Baidu's results page for
        `payload.query`, with the pages it cites, and the rest of that page:
        organic results, ads, related searches, news, videos, notes, products,
        images, places and Baidu's other cards; it always searches from mainland
        China, and a query Baidu shows no AI answer for completes with `card:
        null` and the rest of the page. `BING` is accepted as an earlier
        spelling of `BING_SEARCH`, and `BING_COPILOT` and `MICROSOFT_COPILOT` as
        earlier spellings of `COPILOT`; responses echo the new names. `SOCIAL`
        reads public YouTube, Instagram and Threads data: `payload.platform`
        picks the site and `payload.action` what to read (SocialPayload,
        SocialResult); other `payload.platform` values are rejected with 403
        ENGINE_PRIVATE or 400 VALIDATION_ERROR. `ADS` reads the public ad
        libraries of Meta, Google, LinkedIn and TikTok (AdsPayload, AdsResult):
        `payload.platform` is `meta_ad_library`, `google_ads_transparency`,
        `linkedin_ad_library`, `tiktok_ad_library` or `tiktok_creative_center`,
        and `payload.action` picks `search` (the default: the ads that match the
        platform's search inputs, each with its days run where the library gives
        dates and a `summary` of the response, charged 0.5 credits for every 30
        ads returned, with a `nextCursor` to read the ads after them),
        `advertisers` (the advertisers whose names match `payload.query`, on
        Meta, Google and the TikTok Ad Library), `ad` (one ad by
        `payload.libraryId` with its advertiser and the transparency the library
        publishes) or `advertiser` (one Meta advertiser by `payload.pageId`),
        0.5 credits each. Private engines (for example CLAUDE) are rejected with
        403 ENGINE_PRIVATE. CITATION_ANALYSIS, PROMPT_RESEARCH and GEO_SCORE
        tasks are created through their own endpoints (POST
        /v1/citation-analysis, POST /v1/prompt-research, POST /v1/geo-score) and
        are rejected here with 400 USE_DEDICATED_ENDPOINT; they appear in this
        list because their tasks report them. SEARCH is the name a search made
        through POST /v1/search answers under, and WEB_SEARCH the id
        capabilities, key scopes and usage list it by; both are rejected here
        with 400 USE_DEDICATED_ENDPOINT. GEO_AUDIT, SOURCE_INFLUENCE and
        CITATION_ATTRIBUTION are accepted as earlier names of CITATION_ANALYSIS;
        responses echo CITATION_ANALYSIS.
      enum:
        - CHATGPT
        - PERPLEXITY
        - GEMINI
        - AIMODE
        - GOOGLE_AIMODE
        - GOOGLE
        - GOOGLE_AIO
        - GOOGLE_SERP
        - GOOGLE_PLACES
        - GOOGLE_NEWS
        - NAVER_AI_BRIEF
        - NAVER_AI_TAB
        - NAVER_AI_MODE
        - NAVER
        - NAVER_SERP
        - COMMERCE_SERP
        - COMMERCE_PRODUCT
        - SOCIAL
        - ADS
        - BING_SEARCH
        - BRAVE_SEARCH
        - BING
        - COPILOT
        - BING_COPILOT
        - MICROSOFT_COPILOT
        - BING_AIMODE
        - BING_COPILOT_SEARCH
        - COPILOT_SEARCH
        - META_AI
        - QWEN
        - DOUBAO
        - BAIDU_WENXIN
        - BAIDU_AI_SEARCH
        - CITATION_ANALYSIS
        - GEO_AUDIT
        - SOURCE_INFLUENCE
        - CITATION_ATTRIBUTION
        - PROMPT_RESEARCH
        - GEO_SCORE
        - SEARCH
        - WEB_SEARCH
        - WEB_SCRAPE
  responses:
    CommerceTaskRunning:
      description: >-
        The task had not ended when the wait was over. It keeps running; poll
        `Location` or wait for the webhook.
      headers:
        Location:
          description: 'Where to poll the task: `/v1/async/task/{id}`.'
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AsyncResponse'
          examples:
            search:
              summary: A search still running
              value:
                success: true
                task:
                  id: 8f2c1e40-0000-0000-0000-000000000000
                  taskType: COMMERCE_SERP
                  status: QUEUED
                  priority: 1
                  createdAt: '2026-07-09T04:12:00.000Z'
                  latencyMs: null
                credits:
                  creditsToCharge: 0
                  creditsCharged: 0
            product:
              summary: A product still running
              value:
                success: true
                task:
                  id: 8f2c1e40-0000-0000-0000-000000000000
                  taskType: COMMERCE_PRODUCT
                  status: QUEUED
                  priority: 1
                  createdAt: '2026-07-09T04:12:00.000Z'
                  latencyMs: null
                credits:
                  creditsToCharge: 0
                  creditsCharged: 0
    CommerceUnknownField:
      description: >-
        `VALIDATION_ERROR`: the body is not a JSON object, or it has a field
        this endpoint does not take; `details` names the field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: Request validation failed
              details:
                - field: site
                  message: >-
                    unknown field; Walmart search takes query, limit, sort,
                    minPrice, maxPrice, page, brand, soldByWalmart,
                    fastDelivery, minRating, idempotencyKey, priority, webhook
              timestamp: '2026-07-09T04:12:00.000Z'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: MISSING_API_KEY
              message: Missing or invalid API key
              timestamp: '2026-07-09T04:12:00.000Z'
    InsufficientCredits:
      description: '`INSUFFICIENT_CREDITS`: the balance is below the price of the task.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: INSUFFICIENT_CREDITS
              message: insufficient credits (need 2)
              timestamp: '2026-07-09T04:12:00.000Z'
    CommerceKeyScopeDenied:
      description: >-
        `KEY_SCOPE_DENIED`: the key's Allowed engines leave out `COMMERCE_SERP`,
        for a search, or `COMMERCE_PRODUCT`, for a product page.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: KEY_SCOPE_DENIED
              message: This API key is not allowed to submit taskType 'COMMERCE_SERP'
              timestamp: '2026-07-09T04:12:00.000Z'
    IdempotencyKeyExpired:
      description: >-
        A task with this `idempotencyKey` exists but is past its retention
        window, so its result can no longer be read. A key whose task can still
        be read is answered with that task instead.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: RESOURCE_ALREADY_EXISTS
              message: Task already exists.
              details:
                taskId: 8f2c1e40-0000-0000-0000-000000000000
              timestamp: '2026-07-09T04:12:00.000Z'
    PayloadTooLarge:
      description: '`PAYLOAD_TOO_LARGE`: the body exceeds 1 MiB. Rejected before parsing.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: PAYLOAD_TOO_LARGE
              message: request body exceeds 1 MiB
              timestamp: '2026-07-09T04:12:00.000Z'
    CommerceSearchInvalid:
      description: >-
        `VALIDATION_ERROR`: a field is missing, of the wrong type or out of
        range, such as a sort, filter or page value the store does not take, a
        limit above the store's, or a minPrice above maxPrice; `details` names
        the field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: COMMERCE_SERP walmart minRating must be one of 4
              details:
                - field: minRating
                  message: COMMERCE_SERP walmart minRating must be one of 4
              timestamp: '2026-07-09T04:12:00.000Z'
    TaskLimitExceeded:
      description: >-
        Retry after the `Retry-After` header (seconds). `QUEUE_LIMIT_EXCEEDED`:
        the account already has 1,000,000 queued tasks.
        `KEY_DAILY_CREDIT_LIMIT`: the key used up its daily credit limit.
        `SUB_ACCOUNT_CREDIT_LIMIT`: the sub-account would exceed its
        `monthlyCreditLimit`. A task past the plan or contract concurrency limit
        is not refused: it is accepted, polls as `QUEUED`, and starts as running
        tasks finish.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: QUEUE_LIMIT_EXCEEDED
              message: >-
                Queue limit exceeded. Maximum 1000000 queued tasks allowed per
                account
              details:
                limit: 1000000
                retryAfterSec: 30
              timestamp: '2026-07-09T04:12:00.000Z'
    CommerceUnavailable:
      description: >-
        Retry after the `Retry-After` header (seconds). `QUEUE_BACKPRESSURE`:
        this engine's queue is full. `SERVER_OVERLOADED`: admission is
        saturated, or the task queue as a whole is full. `DB_UNAVAILABLE`: task
        storage did not answer. `ENGINE_UNAVAILABLE`: this engine is temporarily
        not accepting tasks; `details.resumeAt`, when present, is when it
        expects to take tasks again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: DB_UNAVAILABLE
              message: Task storage unavailable. Retry shortly.
              details:
                retryAfterSec: 2
                retryable: true
              timestamp: '2026-07-09T04:12:00.000Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer <key>`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.