Thirteen tags, twenty characters: what Etsy actually accepts

Every seller knows the thirteen tag slots. Fewer people know what happens at the edges: what the write endpoint refuses, what it trims, and what it accepts without complaint and then does not store. That last category is the interesting one, because a tool can report success on it and be wrong.

The hard limits

These are enforced. Break one and the call fails with an error you can read.

The useful thing about a hard limit is that you can check it before you spend a call. A fourteenth tag is not a question about Etsy’s behaviour; it is arithmetic. Stallsy marks it while you type, and the call is never made.

The rate limits are 10,000 calls a day and 10 per second. Those sound generous until you notice there is no bulk write: editing 200 listings is 200 separate calls. A tool that wastes calls discovering limits it could have checked locally is spending your quota on nothing.

The trap: arrays are not repeated keys

Tags and materials are lists. The natural way to send a list in a form‑encoded request is to repeat the key:

tags=dragon&tags=figurine&tags=resin

Etsy accepts this request. It returns success. It then stores one tag — the last one.

The correct encoding is a single comma‑separated value:

tags=dragon,figurine,resin

This is the shape of the whole problem. The request was well‑formed, the server said yes, and the outcome was wrong.

Fields that depend on another field

Some fields are only stored when a second setting is on. Send personalization_instructions to a listing where is_personalizable is false, and the instructions are accepted and discarded. No error. The response looks the same as a successful write.

We keep a small table of these dependencies and check it before writing. When the parent setting is off, we do not send the child field and pretend it worked — we say the field did not land and why. It is a shorter, less satisfying message than “saved”, and it is the true one.

Verify what you wrote

The habit that follows from all of this is simple: read the response back and compare it to what you sent. Etsy’s update call returns the listing as it now stands. That is free ground truth, in the reply you already received.

Stallsy compares field by field and reports three categories rather than one:

• Written — sent, and the response confirms the new value.
• Not written — rejected, with the reason.
• Unverified — sent, no error, but the response does not show the new value. This is the category most tools quietly fold into “success”.

One more thing: do not retry writes

Retrying a failed read is free. Retrying a failed write is not, because the most common failure is the network dropping after Etsy received the request. Retry and you may apply the same change twice, or overwrite a value that had already changed.

The one safe exception is a rate‑limit response. That one is Etsy explicitly telling you it did not process the request, and asking you to come back later.

What this means for you

You cannot see any of this from the outside, which is exactly why it matters when you pick a tool that writes to your shop. The question worth asking is not how many fields it can edit. It is what it does when a field does not land: tell you, or call it a success.