Microsoft Teams Bot Framework · error code

Teams error 500 ServiceError: 500 - internal server error at the Connector

Permanent - do not retryHTTP 500Service errors

Last verified against Microsoft Learn - Status codes from bot conversational APIs

What Teams returns
*various

What error 500 ServiceError means

Something failed inside Microsoft's service while processing your request. The status table lists 500 as code ServiceError with various messages and - unusually - documents no retry: the guidance is to report persistent cases through the developer community channels, in contrast to 502, 503, and 504, which are explicitly retryable with backoff.

Two hygiene points keep a 500 investigation short. First, capture the X-Correlating-OperationId response header the Connector attaches to every response - Microsoft's API reference asks you to include it when reporting, since it indexes their internal log entry. Second, be sure whose 500 you are looking at: your own endpoint returning 500 to inbound activities is a different failure (your bug, debugged with Application Insights per Microsoft's troubleshoot-500 guide) than the Connector returning 500 to your outbound send. The direction of the call tells you which side owns the fix.

What it looks like

HTTP/1.1 500 Internal Server Error
X-Correlating-OperationId: 5f1b3c...

{
  "error": {
    "code": "ServiceError",
    "message": "..."
  }
}

Why it happens

  • A transient or systemic fault inside the Bot Framework/Teams service while handling your call.
  • A service incident (check the Azure status page and Teams admin center service health).
  • Rarely, a payload that triggers an unhandled edge case server-side - if one specific message always 500s, suspect this.

How to fix Teams error 500 ServiceError

  1. 1Log the full ErrorResponse body and the X-Correlating-OperationId header for the failing call.
  2. 2Check Azure/Microsoft 365 service health before assuming a local cause.
  3. 3If one payload reproducibly fails, minimize it and treat the reduced case as a bug report; do not blind-retry - 500 is documented as non-retryable.
  4. 4For persistent failures, report through the Teams developer community with the operation ID attached.

How to stop it recurring

You cannot prevent Microsoft's 500s, but you can be diagnosable: persist operation IDs with every failed send, alert on 500-rate rather than individual events, and keep your own endpoint's 500s separately dashboarded (Application Insights exception queries, as the Azure troubleshooting guide walks through) so the two never blur in an incident.

Official reference: Microsoft Learn - Status codes from bot conversational APIs. See all Teams error codes or the Teams limits and quotas.

Related codes

Error 500 ServiceError - quick answers

What does Teams error 500 ServiceError mean?

Something failed inside Microsoft's service while processing your request. The status table lists 500 as code ServiceError with various messages and - unusually - documents no retry : the guidance is to report persistent cases through the developer community channels, in contrast to 502 , 503 , and 504 , which are explicitly retryable with backoff. Two hygiene points keep a 500 investigation short.

How do I fix Teams error 500 ServiceError?

1. Log the full ErrorResponse body and the X-Correlating-OperationId header for the failing call. 2. Check Azure/Microsoft 365 service health before assuming a local cause. 3. If one payload reproducibly fails, minimize it and treat the reduced case as a bug report; do not blind-retry - 500 is documented as non-retryable. 4. For persistent failures, report through the Teams developer community with the operation ID attached.

Should I retry after error 500 ServiceError?

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 Teams by hand

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