Microsoft Teams bot error codes, explained one by one

In the HTTP response to your outbound Connector API calls (send, update, delete, create conversation). The body is an ErrorResponse object with a stable code string such as BotDisabledByAdmin or Throttled and a human-readable message. In the C# SDK these surface as ErrorResponseException or HttpOperationException; in Node the connector call rejects with an error carrying the statusCode. Inbound failures - your endpoint erroring - never appear here; they show up in your own logs and as 502s reported by the channel.

The most common single cause is an expired Microsoft Entra client secret: secrets live at most 24 months, and expiry produces AADSTS7000222 in your logs while Teams shows users nothing at all. Check the app registration's Certificates & secrets blade first. Other silent stoppers are a rotated-but-not-deployed secret, an admin blocking the app (403 BotDisabledByAdmin), and an endpoint deployment that broke the messaging URL.

Teams fires no event when a user blocks or uninstalls a personal-scope app. The only signal is the error on your next send: 403 with code ConversationBlockedByUser on the reactive path, or 403 with subCode MessageWritesBlocked ("Thread is blocked from message writes.") on proactive sends. Microsoft explicitly documents compiling these per-user 403s into a blocked-users report. Treat the first such 403 as an unsubscribe and stop sending.

Microsoft's retry guidance is explicit: retry 429 (using the Retry-After header), and retry 412, 502, 503, and 504 with exponential backoff plus jitter. Do not retry 400, 401, 403, 404, 405, 413, or 500 - the documented action for those is to fix the cause or stop sending. Retrying policy blocks like BotDisabledByAdmin just burns rate-limit budget without changing the outcome.

Three budgets: per bot per thread (for send-to-conversation: 7 operations/second, 8/2s, 60/30s, 1,800/hour), per thread across all bots (14 sends/second, 16/2s), and a global 50 requests per second per app per tenant. Roster and conversation reads have separate windows. Microsoft warns the exact values can change, so honor Retry-After and back off rather than hard-coding the numbers.

It means your messaging endpoint failed - it threw, timed out, or returned 5xx - and the channel is reporting that as a 502 with body code BotRejectedActivity and message "Failed to send activity: bot returned an error". The fix is on your side: enable Application Insights, query exceptions, and implement the adapter's OnTurnError handler. A 502 on your own outbound send call is different: that one is a documented transient and should be retried.

Slow handlers. For invoke interactions (message extensions, dialogs) the documented budget is five seconds; Teams retries twice and ignores late responses, so a six-second handler executes three times and shows the user "Unable to reach the app". Regular activities are also redelivered when your endpoint answers slowly. Acknowledge fast, do heavy work asynchronously, and make side effects idempotent by activity ID.

Bot authentication needs three settings to agree: the Microsoft App ID (Entra application), the client secret issued for exactly that app, and the tenancy (MicrosoftAppType plus MicrosoftAppTenantId for single-tenant bots). Each mismatch has its own signature: AADSTS7000215 for a wrong secret, AADSTS700016 for a wrong app-or-tenant pairing, AADSTS7000222 for an expired secret. Verify the triangle with one cURL token request before touching any other layer.

The documented bot message size limit is 100 KB, measured approximately over the whole activity - text, image links, mentions, reactions - encoded as UTF-16, excluding base64-encoded images. Microsoft recommends staying within 80 KB to guarantee delivery. Exceeding it returns HTTP 413 (RequestEntityTooLarge) with error code MessageSizeTooBig, which is not retryable: split the content or link out to it.

No. The Connector API documents 200 and 201 as success and 202 as "the request was accepted for processing" - normal asynchronous delivery, with the ResourceResponse still carrying the activity ID you need for later updates or deletes. Treat any 2xx as success and store the returned id. Only 4xx and 5xx responses carry an ErrorResponse object and need handling.