Errors Reference

Branchable, category-driven error codes across the Lists API, with causes, context, and a production handling policy

Overview

slackLists.items.update and Lists' other write and read methods all return {"ok": false, "error": "<code>"} on failure. This page groups the documented error codes — across every slackLists.* method used elsewhere in this section, not just items.update — by cause, so a Worker can branch on body.error instead of treating every non-ok response the same way. See "Production Error Handling" below for how to turn that branching into an actual retry/halt/alert policy.

The Full Table

Select-Column Errors

invalid_option_id is the error you will see most often once a select column is in production use. It fires in two distinct situations that look identical on the wire:

• The value sent is a label, not a value slug — see Select Columns for why labels are never accepted.

• The option used to exist and was deleted by a human editing the list schema in the UI — see Schema Mutability. A cached slug map does not know this happened; re-read list_metadata.schema via items.info when this error is unexpected.

invalid_input_type and invalid_array_arg are both shape errors rather than value errors — see Writing List Items for the typed-value-key table and why almost every value is array-wrapped even for a single value.

Stale-ID Errors

invalid_column_id / column_not_found and invalid_row_id / row_not_found both mean a persisted ID no longer resolves. items.info reports the same row-missing condition under its own spellings, record_not_found and record_deleted — same cause, different method, different wording, so a code-matching branch has to check both families to catch a stale row id regardless of which method surfaced it. items.create's duplicated_item_not_found is the same shape of problem one level removed: the row you asked to duplicate from is itself gone.

Since there is no slackLists.info or slackLists.list to re-discover a list's structure, and no "find row by external key" endpoint, the only recovery for a stale row id is a full paginated read of the list to rebuild the mapping from whatever your own primary key is stored in (for example, a text column mirroring the source row's ID). A stale column_id means the list's schema changed out from under you — re-read list_metadata.schema via items.info.

Permission and Access Errors

list_not_found is overloaded: it is the generic "bad list_id" error, but it is also what items.update returns when the token's holder lacks access to an otherwise-valid list — there is a community report (slackapi/deno-slack-sdk#472) of exactly this happening despite the list being shared into the bot's channel. Do not assume list_not_found always means a typo'd or deleted ID; it can also mean an access problem. See Select Columns for why bot-creates-the-list sidesteps the access question rather than needing to disambiguate this error.

no_permission, access_denied, and permission_denied are the more direct access-denied family, distinct from the plan-gate and scope errors below. team_access_not_granted is the same family under a different name — it shows up across most slackLists.* methods, not just items.update, whenever the token's workspace-level access doesn't cover this list.

Because list_not_found can mean either "bad ID" or "access problem" and there is no way to tell which from the wire, the category taxonomy below gives it its own category — access_or_stale_id — rather than folding it into either the stale-ID group above or the access-denied family here.

Plan and Scope Errors

Four errors gate on different things and are easy to conflate:

• paid_teams_only — the workspace itself is on a free plan; Lists requires a paid plan.

• lists_disabled_user_team — the workspace is paid, but a workspace admin has turned Lists off. This is an admin toggle, not a billing state, and both errors can look identical from inside a Worker's error-handling branch unless you check for both explicitly.

• archive_not_supported — items.list's archived-items query isn't available on the caller's plan; a third, narrower plan gate distinct from the two above.

• missing_scope — the token itself lacks lists:write. Unlike the errors above, this is fixable by reinstalling the app with the correct scope, not by anything the workspace admin or plan tier controls.

Rich Text Errors

invalid_blocks and invalid_text_block both mean a text/notes column received something other than a valid Block Kit rich_text structure — most commonly a plain string, which text columns never accept on the write path (see Writing List Items).

Rate Limiting

slackLists.items.update sits on Tier 3 (50+ requests/min), per both the docs and the Java SDK's machine-readable rate_limit_tiers.json — the two sources agree for this method. ratelimited carries a Retry-After header stating how many seconds to wait before retrying; honor it rather than retrying immediately or on a fixed interval.

Production Error Handling: Branch on Category, Not Code

A Worker that branches on the literal error string ends up re-deriving the same handful of policies over and over, once per code. It's more robust to map every code into a small category taxonomy first, then drive retry/halt/alert policy off the category — new codes Slack adds later slot into an existing bucket instead of falling through to a default.

The first six rows — scope, auth, access, access_or_stale_id, schema, plan — plus capacity are all permanent configuration errors: retrying cannot fix them, because nothing about the request changes on the next attempt. On any code in these categories, mark the List registration unhealthy, halt sync against that list, and alert — a human (or a schema-drift redeploy, see Schema Mutability) has to change something before sync can resume safely.

transient and rate_limit are the opposite: back off and retry. ratelimited carries a Retry-After header telling you how long; the generic server-error family (internal_error, fatal_error, service_unavailable, request_timeout) doesn't, so use a capped exponential backoff instead.

stale_id is neither — it isn't a config problem to halt on, nor pure noise to retry through. It means your locally persisted ID no longer resolves, which is exactly the signal a reconcile pass exists to correct: feed it into the next reconcile cycle to rebuild the mapping rather than either halting the whole sync or blindly retrying the same stale ID.

Related

For the request/response contract these errors apply to, see Writing List Items. For the select-value rules behind invalid_option_id, see Select Columns. For why the schema itself is closed to most API-driven changes, see Schema Mutability. For what the capacity error over_row_maximum means and how to avoid triggering it in normal operation, see Item Caps and Auto-Archive.