Discord API · error code

Discord error 220003: Webhooks can only create threads in forum channels

Permanent - do not retryHTTP 400Validation and request shape

Last verified against Discord Developer Docs - Opcodes and status codes

What Discord returns
Webhooks can only create threads in forum channels

What error 220003 means

You executed a webhook with the thread_name parameter (which asks Discord to create a new thread and post the message as its starter) but the webhook's channel is not a forum or media channel. In regular text channels, webhooks can post into an existing thread using the thread_id query parameter, but they cannot create a thread from scratch. Thread creation via webhook is reserved for forum-style channels, where every post is a thread.

Integrations that were configured against a text channel and later had forum behavior bolted on hit this; so do bots that reuse one execute-webhook function for both channel kinds. The message itself is otherwise valid, so the fix is purely about which parameter you pass.

What it looks like

{
  "message": "Webhooks can only create threads in forum channels",
  "code": 220003
}

Why it happens

  • thread_name passed when executing a webhook in a text or announcement channel
  • Webhook moved from a forum channel to a text channel by an admin
  • Shared code path that always sets thread_name

How to fix Discord error 220003

  1. 1Check the webhook's channel type (GET /webhooks/{id}/{token} then GET /channels/{channel_id}); only send thread_name when type is 15 or 16
  2. 2In text channels, create the thread with the bot token first, then execute the webhook with ?thread_id=
  3. 3Or drop thread_name and post directly to the channel

How to stop it recurring

Branch your webhook sender on channel type at configuration time and store the resulting mode (post-to-channel, post-to-thread, create-forum-post) with the webhook record. Re-validate when a WEBHOOKS_UPDATE event fires.

Document clearly, for anyone who pastes a webhook URL into your bot, that forum posts require a forum-channel webhook; a channel-type check at paste time saves a support conversation later.

The webhook execution parameters differ just enough between channel kinds to deserve their own tests. The webhook capability table, including thread creation and posting rules, is on the Discord limits page, and the webhook debugging guide covers isolating parameter errors from transport errors.

Store the resolved channel type next to every saved webhook so the sender never has to guess at execution time.

Official reference: Discord Developer Docs - Opcodes and status codes. See all Discord error codes or the Discord limits and quotas.

Related codes

Error 220003 - quick answers

What does Discord error 220003 mean?

You executed a webhook with the thread_name parameter (which asks Discord to create a new thread and post the message as its starter) but the webhook's channel is not a forum or media channel. In regular text channels, webhooks can post into an existing thread using the thread_id query parameter, but they cannot create a thread from scratch.

How do I fix Discord error 220003?

1. Check the webhook's channel type (GET /webhooks/{id}/{token} then GET /channels/{channel_id}); only send thread_name when type is 15 or 16 2. In text channels, create the thread with the bot token first, then execute the webhook with ?thread_id= 3. Or drop thread_name and post directly to the channel

Should I retry after error 220003?

No. Retrying the same request produces the same error; the condition has to be fixed first. Treat it as a permanent failure for that message and surface it, rather than looping.

Stop debugging Discord by hand

Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.