> ## Documentation Index > Fetch the complete documentation index at: https://docs.alura.io/llms.txt > Use this file to discover all available pages before exploring further. # Update a listing > Changes one listing of your connected Etsy shops on Etsy: title, description, tags (the whole list, or `tags_add`/`tags_remove` against the tags it has on Etsy right now), materials, category, maker fields, section, shipping profile, return policy, processing profile, production partners, auto-renew, `state: "inactive"`, and the price, quantity and SKU of every offering. Every field you send is sent to Etsy, even one equal to Alura's copy; fields you leave out are untouched; an unknown field is 400. `null` clears only `section_id` and `return_policy_id`. A listing with variations is 409 `listing_has_variations` for price, quantity and processing profile unless `apply_to: "all_variants"` (never for SKU). A listing in a running A/B test is 409 `listing_in_ab_test`. `adjust_price` and `adjust_quantity` need an `Idempotency-Key`. `tags_add` and `tags_remove` are applied to the tags Etsy holds when the write runs, read just before the change; Etsy has no conditional update, so a tag another tool writes to Etsy in that moment can be lost, and the change records any difference between the tags sent and those Etsy kept. Answers 200 with the listing as Etsy returned it and its change, or 202 with the change while Etsy is still answering; `dry_run=true` shows what it would send. Needs the `listings:write` scope and the Listing optimization workspace permission. Costs 1 API credit when the change lands on Etsy, nothing when it fails; `dry_run` is free. Cost: 1 API credit per write. ## OpenAPI ````yaml /openapi.json patch /v1/workspace/listings/{id} openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/workspace/listings/{id}: patch: summary: Update a listing description: >- Changes one listing of your connected Etsy shops on Etsy: title, description, tags (the whole list, or `tags_add`/`tags_remove` against the tags it has on Etsy right now), materials, category, maker fields, section, shipping profile, return policy, processing profile, production partners, auto-renew, `state: "inactive"`, and the price, quantity and SKU of every offering. Every field you send is sent to Etsy, even one equal to Alura's copy; fields you leave out are untouched; an unknown field is 400. `null` clears only `section_id` and `return_policy_id`. A listing with variations is 409 `listing_has_variations` for price, quantity and processing profile unless `apply_to: "all_variants"` (never for SKU). A listing in a running A/B test is 409 `listing_in_ab_test`. `adjust_price` and `adjust_quantity` need an `Idempotency-Key`. `tags_add` and `tags_remove` are applied to the tags Etsy holds when the write runs, read just before the change; Etsy has no conditional update, so a tag another tool writes to Etsy in that moment can be lost, and the change records any difference between the tags sent and those Etsy kept. Answers 200 with the listing as Etsy returned it and its change, or 202 with the change while Etsy is still answering; `dry_run=true` shows what it would send. Needs the `listings:write` scope and the Listing optimization workspace permission. Costs 1 API credit when the change lands on Etsy, nothing when it fails; `dry_run` is free. Cost: 1 API credit per write. operationId: workspace.listings.update parameters: - name: id in: path required: true schema: description: The Etsy listing ID. A listing outside the workspace is 404. type: string pattern: ^[0-9]{1,20}$ example: '1834720561' - name: dry_run in: query required: false description: >- `true`: plan the write and send nothing: what it would change, the Etsy calls it would make, and nothing reserved, charged or recorded. Free; counts toward the per-minute write limit. schema: type: boolean - name: Idempotency-Key in: header required: false description: >- Makes a retry safe: the same key with the same request within 24 hours answers from the first write (with `Idempotent-Replayed: true`) and never writes to Etsy twice; a write that failed with nothing written (`Retry-After` set) is tried again under it. The same key with a different request is a 409 `conflict`; while the first request still runs, 409 `idempotency_processing` (or the same 202). Required for relative changes such as `adjust_price`. schema: type: string minLength: 1 maxLength: 255 requestBody: required: false content: application/json: schema: type: object properties: title: description: The title, 1-140 characters. type: string minLength: 1 maxLength: 140 description: description: The description; replaces the whole text. type: string maxLength: 50000 tags: description: >- Every tag, at most 13; replaces them all (an empty list removes every tag). Not with `tags_add` or `tags_remove`. maxItems: 13 type: array items: type: string minLength: 1 maxLength: 30 tags_add: description: >- Tags to add to the tags the listing has on Etsy right now (read live when the write runs, not from Alura's copy); one already there is kept once. The result may have at most 13 tags. minItems: 1 maxItems: 13 type: array items: type: string minLength: 1 maxLength: 30 tags_remove: description: >- Tags to remove from the tags the listing has on Etsy right now, case-insensitive; one the listing does not have is ignored. minItems: 1 maxItems: 13 type: array items: type: string minLength: 1 maxLength: 30 materials: description: Every material, at most 13; replaces them all. maxItems: 13 type: array items: type: string minLength: 1 maxLength: 45 category_id: description: >- Etsy's category (its `taxonomy_id`), from browse_categories or GET /v1/categories. type: string pattern: ^[1-9][0-9]{0,9}$ who_made: description: Etsy's `who_made`. type: string enum: - i_did - someone_else - collective when_made: description: >- Etsy's `when_made`, for example `made_to_order`, `2020_2026` or `before_2007`. type: string pattern: ^[a-z0-9_]{1,20}$ is_supply: description: 'true: a craft supply or tool; false: a finished product.' type: boolean section_id: anyOf: - description: >- A section of the listing's shop; `null` takes the listing out of its section. A section of another shop is 404. type: string pattern: ^[0-9]{1,20}$ - type: 'null' shipping_profile_id: description: >- A shipping profile of the listing's shop. A profile of another shop is 404. type: string pattern: ^[0-9]{1,20}$ return_policy_id: anyOf: - description: >- A return policy of the listing's shop; `null` removes the listing's policy. A policy of another shop is 404. type: string pattern: ^[0-9]{1,20}$ - type: 'null' processing_profile_id: description: >- A processing profile of the listing's shop (list them with GET /v1/workspace/processing-profiles); set on every offering, so a listing with variations is 409 `listing_has_variations` without `apply_to: "all_variants"`. A profile of another shop is 404. type: string pattern: ^[0-9]{1,20}$ production_partner_ids: description: >- Every production partner who helps make the item; replaces them all (an empty list removes them). maxItems: 50 type: array items: description: >- A production partner of the listing's shop. A partner of another shop is 404. type: string pattern: ^[0-9]{1,20}$ should_auto_renew: description: >- true: Etsy renews the listing automatically when it expires (a listing fee each time). type: boolean state: description: >- `inactive` deactivates the listing on Etsy. Publishing (`active`) is not available through this operation yet. type: string enum: - inactive - active price: description: >- The new price of every offering in the listing's own currency, as a decimal string such as "24.99" (a number with at most 2 decimals is accepted too); above 0 and at most 50,000 in the listing's currency. type: - string - number adjust_price: type: object properties: kind: type: string enum: - absolute - percentage description: >- `absolute`: add `value` (negative to lower it) in the listing currency; `percentage`: change by `value` percent. value: type: number required: - kind - value additionalProperties: false description: >- A relative price change of every offering. Needs a request key (REST `Idempotency-Key`, MCP `request_id`), so a retry never applies it twice. quantity: description: The quantity in stock of every offering, 0-999. type: integer minimum: 0 maximum: 999 adjust_quantity: description: >- Add this many (negative to remove; never below 0) to every offering's quantity. Needs a request key, so a retry never applies it twice. type: integer minimum: -999 maximum: 999 sku: description: >- The SKU of every offering, at most 32 characters. Only on a listing without variations. type: string minLength: 1 maxLength: 32 apply_to: description: >- `all_variants`: apply `price`, `adjust_price`, `quantity`, `adjust_quantity` or `processing_profile_id` to every variant of a listing with variations (without it such a listing is 409 `listing_has_variations`). Never for `sku`. type: string enum: - all_variants additionalProperties: false example: title: Personalized ceramic mug, 11 oz responses: '200': description: >- OK: the write landed on Etsy (or, with `dry_run=true`, what it would do). headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' Idempotent-Replayed: description: '`true` when this answers an earlier request with the same key.' schema: type: string Alura-Write-Budget-Remaining: description: The shop's Etsy write budget left, when SDS reported it. schema: type: integer Alura-Write-Deduplicated: description: >- Set when this write was answered, free, from an earlier identical write: that write's change id (`chn_...`). Nothing was sent to Etsy again. schema: type: string content: application/json: schema: anyOf: - type: object properties: object: type: string const: workspace.listing id: type: string description: Etsy ID, as a string. shop_id: type: string description: Etsy ID, as a string. title: type: - string - 'null' description: type: - string - 'null' url: description: The listing on Etsy. type: - string - 'null' state: description: >- Etsy's listing state, for example `active`, `inactive` or `draft`. type: - string - 'null' price: anyOf: - type: object properties: amount: type: string description: Decimal string in the listing's own currency. currency: type: string description: ISO 4217 code. usd: description: >- The same price in USD at the request's exchange rates, as a decimal string; null when no rate is known. type: - string - 'null' required: - amount - currency - usd additionalProperties: false description: The listing's price. - type: 'null' description: >- The listing's price as Etsy answered; `usd` is null unless the listing is priced in USD. quantity: anyOf: - type: integer - type: 'null' description: >- The listing's total quantity across its enabled offerings, as Etsy and get_my_listing count it (not the per-offering value a request sends: 3 on each of 2 variants is 6). skus: anyOf: - type: array items: type: string - type: 'null' tags: anyOf: - type: array items: type: string - type: 'null' materials: anyOf: - type: array items: type: string - type: 'null' category: anyOf: - type: object properties: id: type: string description: Etsy ID, as a string. required: - id additionalProperties: false - type: 'null' description: Etsy's category (`category_id` in the request). section: anyOf: - type: object properties: id: type: string description: Etsy ID, as a string. required: - id additionalProperties: false - type: 'null' description: The shop section; null when the listing is in none. shipping_profile_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' return_policy_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' processing_profile_id: anyOf: - type: string description: Etsy ID, as a string. - type: 'null' description: >- The processing profile every offering has; null when they differ or Etsy did not say. production_partner_ids: anyOf: - type: array items: type: string description: Etsy ID, as a string. - type: 'null' who_made: type: - string - 'null' when_made: type: - string - 'null' is_supply: type: - boolean - 'null' should_auto_renew: type: - boolean - 'null' updated_at: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: When Etsy last changed the listing. as_of: type: string description: When Etsy answered the write. change: type: object properties: id: type: string description: >- `chn_...`: GET /v1/workspace/changes/{id} shows it. status: type: string enum: - succeeded - partial description: >- `partial`: part of the change landed on Etsy, `failed_fields` did not; send a new write for them. applied_fields: type: array items: type: string description: The fields that landed on Etsy. failed_fields: type: array items: type: object properties: field: type: string description: The field, named as in the request. code: type: string description: >- `not_applied`: Etsy did not take this part of the change. New codes may be added. required: - field - code additionalProperties: false description: >- The fields that did not; empty when the write succeeded. required: - id - status - applied_fields - failed_fields additionalProperties: false description: 'The write: its change ID and what landed.' notices: type: array items: type: object properties: code: type: string description: >- `listing_not_returned`, `fields_not_returned` or `varies_by_variant`. New codes may be added. detail: type: string required: - code - detail additionalProperties: false description: >- Why a part of the answer is unknown; empty when nothing is. required: - object - id - shop_id - title - description - url - state - price - quantity - skus - tags - materials - category - section - shipping_profile_id - return_policy_id - processing_profile_id - production_partner_ids - who_made - when_made - is_supply - should_auto_renew - updated_at - as_of - change - notices additionalProperties: false - type: object properties: object: type: string const: workspace.write_plan operation: type: string description: The operation this plan is for. target: type: object properties: type: type: string description: >- What the write changes: `listing`, `shop`, `receipt`. New types may be added. id: type: string description: Etsy ID, as a string. shop_id: type: string description: Etsy ID, as a string. required: - type - id - shop_id additionalProperties: false description: What the write would change. changes: type: array items: type: object properties: field: type: string description: The field, named as in the resource. to: description: The value it would be set to. required: - field - to additionalProperties: false description: What the write would set, field by field. command_hash: type: string pattern: ^[0-9a-f]{64}$ description: >- A hash of the change Alura would send to Etsy: the same request on the same object plans the same change, whatever Alura has stored about it. estimate: type: object properties: etsy_calls_min: type: integer minimum: 0 description: The fewest Etsy calls the write makes. etsy_calls_max: type: integer minimum: 0 description: The most Etsy calls the write makes. required: - etsy_calls_min - etsy_calls_max additionalProperties: false description: Etsy calls the write would make, as a range. write_budget_remaining: anyOf: - type: integer minimum: 0 - type: 'null' description: >- The shop's Etsy calls left in its rolling 24-hour write budget, as of Alura's last count; null when unknown (a dry run does not ask Etsy). consequential: type: boolean description: >- Whether the write needs a confirmation token over MCP (publish, delete, shipments, reverts, price and stock). confirmation_token: description: >- Over MCP, for a consequential write: pass it as `confirmation_token` on the write itself, after the user confirmed. Valid 10 minutes, once. Null otherwise. type: - string - 'null' confirmation_expires_at: description: >- When the confirmation token expires (ISO 8601, UTC); null without one. type: - string - 'null' notices: type: array items: type: object properties: code: type: string description: >- `write_budget_stale`: Alura's last count of the write budget is from before its window moved on, so `write_budget_remaining` is null. New codes may be added. detail: type: string required: - code - detail additionalProperties: false description: >- Why a part of the plan is unknown; empty when nothing is. required: - object - operation - target - changes - command_hash - estimate - write_budget_remaining - consequential - confirmation_token - confirmation_expires_at - notices additionalProperties: false example: object: workspace.listing id: '1834720561' shop_id: '22841907' title: Personalized ceramic mug, 11 oz description: >- A personalized name mug printed with the name you choose. 11oz white ceramic, dishwasher and microwave safe. Made to order in 1-3 days and shipped in a protective box, ready to gift for birthdays, holidays and thank-yous. url: https://www.etsy.com/listing/1834720561 state: active price: amount: '18.50' currency: USD usd: '18.50' quantity: 37 skus: - MUG-NAME-11 tags: - personalized mug - name mug - custom mug - coffee mug - gift for her - birthday gift - ceramic mug - teacher gift - mom gift - custom name - christmas gift - office mug - tea mug materials: - ceramic category: id: '1062' section: id: '3301' shipping_profile_id: '4401' return_policy_id: '4501' processing_profile_id: null production_partner_ids: null who_made: i_did when_made: made_to_order is_supply: false should_auto_renew: true updated_at: '2026-10-17T12:00:00.000Z' as_of: '2026-10-17T12:00:00.000Z' change: id: chn_01JMOCK0000000000000000000 status: succeeded applied_fields: - title failed_fields: [] notices: [] '202': description: >- Accepted: the write is still being applied on Etsy, or its outcome is being checked. Poll the change at `Location`. headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' Location: description: 'The change to poll: `/v1/workspace/changes/{id}`.' schema: type: string Retry-After: description: Seconds to wait before polling. schema: type: integer Idempotent-Replayed: description: '`true` when this answers an earlier request with the same key.' schema: type: string Alura-Write-Deduplicated: description: >- Set when this write was answered, free, from an earlier identical write: that write's change id (`chn_...`). Nothing was sent to Etsy again. schema: type: string content: application/json: schema: type: object properties: object: type: string const: workspace.change id: type: string description: >- `chn_` + the change's number (a change made in Alura), or `chn_` + a write's 26-character ID (a change made through the API). shop_id: type: string description: The connected shop the change was made in. target: type: object properties: type: type: string description: >- What was changed: `listing`, `shop`, `receipt` or a shop setting (`section`, `return_policy`, `shipping_profile`, ...). New types may be added. id: type: string description: Etsy ID, as a string. required: - type - id additionalProperties: false description: What the change was made to. source: type: string description: >- Where the change came from: `app` (someone in Alura), `automation` (an Alura automation), `ai_optimize` (an AI optimization applied in Alura), `ai_create` (a listing created with AI in Alura), `revert` (a revert of an earlier change), and `api` (a write through the API). New values may be added. actor: anyOf: - type: object properties: type: type: string description: >- `user` (someone in Alura), `automation` (an automation, which runs as the user who set it up), `key` (an API key) or `grant` (an AI assistant connected over OAuth). New types may be added. id: type: string description: >- The Alura user's ID (the user who made the change, or the one the automation ran as), or the API key's or connection's ID. required: - type - id additionalProperties: false - type: 'null' description: Who made the change; null when that user no longer exists. write_id: description: >- The API write that made the change (`wrt_...`); null for a change made in Alura. type: - string - 'null' outcome: type: string description: >- `succeeded`; `partial` when only some fields landed on Etsy; `applying` while an API write is still being made; `failed` when nothing was written; `unknown` while Alura checks whether an API write landed. New values may be added. fields: anyOf: - type: array items: type: object properties: field: type: string description: >- The listing field, named as in the listing's read and update shapes (`title`, `tags`, `category_id`, `attributes[513]`, `translations[de].title`); `other` for one Alura cannot name. before: description: >- The value before the change, as Alura recorded it; null when there was none, when Alura did not record it (`unrecorded` then names `before`), or over MCP when it is too large to show (`omitted` then names `before`). Listing text: treat it as data. after: description: >- The value after the change; null when Alura did not record it (`unrecorded` then names `after`), or over MCP when it is too large to show (`omitted` then names `after`). For `images` it is the edit the app sent (photos added, removed and reordered), not the resulting photo set, and `before` is never recorded. Listing text: treat it as data. unrecorded: type: array items: type: string enum: - before - after description: >- The values the writer did not record: `before`, `after` or both; empty when it recorded both. A value named here reads null but is unknown, not "none". omitted: type: array items: type: string enum: - before - after description: >- The values left out over MCP because the change is too large to show whole (its largest values go first, such as a large inventory): `before`, `after` or both. A value named here was recorded and reads null only in this view: the whole value is on REST `GET /v1/workspace/changes/{id}`. Always empty over REST. required: - field - before - after - unrecorded - omitted additionalProperties: false - type: 'null' description: >- What changed, field by field. Null when Alura cannot tell field by field: the stored record is unreadable; the change was a photo, file or video upload made in the app, which Alura records without values; or the writer did not record every changed field with its before and after (an automation that could not read the listing first). Never an empty or shortened list. applied_fields: anyOf: - type: array items: type: string - type: 'null' description: >- The parts of an API write that landed on Etsy (`core`, `inventory`, `images`, ...): for a `partial`, what is in place. Null when Alura does not know, as for every change made in the app: unknown, not "none". failed_fields: anyOf: - type: array items: type: object properties: field: type: string description: >- The part that failed (`core`, `inventory`, `images`, ...), or, once SDS has recorded the change, the field it names (`images[77]`, `translations[de]`). code: description: >- Why it failed, as SDS's error code (`etsy_error`, ...); null when Alura has no code for it (the write's own record, before or without SDS's change record). New values may be added. type: - string - 'null' required: - field - code additionalProperties: false - type: 'null' description: >- The parts of an API write that failed, each with its error code: for a `partial`, what to finish with a new write. Null when Alura does not know, as for every change made in the app: unknown, not "none". before_source: description: >- Where `before` came from: `live` (read from Etsy during the write) or `cache` (Alura's copy); null when unknown, as for every change made in the app. type: - string - 'null' before_as_of: anyOf: - type: string description: ISO 8601, UTC. - type: 'null' description: When `before` was current; null when unknown. revertable: type: boolean description: >- Whether Alura can undo the change; false for every change in this version. not_revertable_reason: description: >- Why it cannot be reverted: `legacy_app_write` for a change the app recorded before writes went through Alura's change log (history only), `revert_unavailable` until reverts arrive. Null when it can. New values may be added. type: - string - 'null' created_at: type: string description: When the change was made. as_of: type: string description: When this record was read. required: - object - id - shop_id - target - source - actor - write_id - outcome - fields - applied_fields - failed_fields - before_source - before_as_of - revertable - not_revertable_reason - created_at - as_of additionalProperties: false '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '409': $ref: '#/components/responses/Problem409' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: >- curl -X PATCH "https://api.alura.io/v1/workspace/listings/1834720561" \ -H "Authorization: Bearer $ALURA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \ -d '{"title":"Personalized ceramic mug, 11 oz"}' - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/workspace/listings/1834720561', { method: 'PATCH', headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c', }, body: JSON.stringify({ "title": "Personalized ceramic mug, 11 oz" }), }); console.log(await res.json()); - lang: python label: Python source: |- import json import os import urllib.request request = urllib.request.Request( "https://api.alura.io/v1/workspace/listings/1834720561", method="PATCH", data=json.dumps({ "title": "Personalized ceramic mug, 11 oz" }).encode(), headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", "Content-Type": "application/json", "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c", }, ) with urllib.request.urlopen(request) as response: print(json.load(response)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/invalid_request title: Invalid request status: 400 code: invalid_request detail: Invalid request suggestion: Fix the request as the detail says, then send it again. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Unauthorized suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.' retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_exhausted title: API credits exhausted status: 402 code: credits_exhausted detail: API credits exhausted suggestion: Upgrade the plan or wait for the monthly reset. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/plan_required title: Plan required status: 403 code: plan_required detail: Plan required suggestion: Upgrade the workspace plan to use this operation. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/not_found title: Not found status: 404 code: not_found detail: Not found suggestion: Check the ID, or search for it first. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/method_not_allowed title: Method not allowed status: 405 code: method_not_allowed detail: Method not allowed suggestion: Use one of the methods in the Allow header. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem409: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/conflict title: Conflict status: 409 code: conflict detail: Conflict suggestion: Reload the resource and retry with its current state. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/rate_limited title: Rate limited status: 429 code: rate_limited detail: Rate limited suggestion: Wait for Retry-After, then retry. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/internal_error title: Internal error status: 500 code: internal_error detail: Internal error suggestion: Retry; if it keeps failing, report the request_id. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_unavailable title: API credits unavailable status: 503 code: credits_unavailable detail: API credits unavailable suggestion: Retry shortly. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - invalid_reference - id_type_mismatch - invalid_keyword - shop_id_required - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - writes_suspended - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - listing_busy - shop_create_busy - idempotency_partial_unverifiable - listing_has_variations - listing_in_ab_test - activation_skipped - idempotency_processing - confirmation_required - write_outcome_unknown - unprocessable - listing_removed_on_etsy - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - write_rate_limited - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - writes_paused - etsy_capacity - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.