Microsoft Teams Bot Framework · error code

Teams error 403 InvalidBotApiHost: InvalidBotApiHost - wrong cloud endpoint (GCC)

ConfigurationHTTP 403Your endpoint & delivery

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

What Teams returns
Invalid agent api host. For GCC tenants, call https://smba.infra.gcc.teams.microsoft.com.

What error 403 InvalidBotApiHost means

Your bot called the public Bot API host for a conversation that lives in a Government Community Cloud (GCC) tenant. The status table documents InvalidBotApiHost with the message "Invalid agent api host. For GCC tenants, call https://smba.infra.gcc.teams.microsoft.com." and - uniquely among the 403s - a retry path: "Update the service URL for the conversation to https://smba.infra.gcc.teams.microsoft.com and retry the request."

Microsoft 365 government clouds are separate service boundaries with their own Bot API hosts. The proactive-messaging guide lists them: public https://smba.trafficmanager.net/teams/, GCC https://smba.infra.gcc.teams.microsoft.com/teams, GCC High https://smba.infra.gov.teams.microsoft.us/teams, DoD https://smba.infra.dod.teams.microsoft.us/teams. The correct behavior is to use the serviceUrl from each incoming activity rather than a hardcoded host - hardcoding the public host is exactly how multi-cloud bots hit this error the day a GCC customer installs them.

The symptom pattern is distinctive: the same code path works for every commercial customer and fails only for one tenant, because the conversation IDs themselves give no hint of which cloud minted them. If your logs show this 403 clustered on a single organization, you are looking at a cloud-boundary problem, not a permissions one.

What it looks like

{
  "error": {
    "code": "InvalidBotApiHost",
    "message": "Invalid agent api host. For GCC tenants, call https://smba.infra.gcc.teams.microsoft.com."
  }
}

Why it happens

  • The service URL was hardcoded to the public smba.trafficmanager.net host instead of taken from the incoming activity.
  • Cached conversation references store the conversation ID but not its serviceUrl, and sends default to the public cloud.
  • A GCC tenant installed the app and the proactive sender never branched on cloud environment.
  • A conversation reference exported from one environment was imported into another that talks to a different cloud.

How to fix Teams error 403 InvalidBotApiHost

  1. 1Follow the documented retry: switch the request's base URL to https://smba.infra.gcc.teams.microsoft.com for this conversation and resend.
  2. 2Persist serviceUrl alongside every conversation reference and always build Connector clients from it.
  3. 3Audit the codebase for hardcoded smba hosts; keep the documented global URLs only as fallbacks per cloud.
  4. 4Test with a GCC test tenant if government customers are in scope.

How to stop it recurring

Never hardcode a Bot API host. The incoming activity's serviceUrl is authoritative for replies, and stored conversation references must carry it for proactive sends - Microsoft's proactive-messaging warning says precisely this. If you operate in multiple clouds, add the cloud environment to your conversation records so a misrouted send is queryable rather than mysterious.

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

Related codes

Error 403 InvalidBotApiHost - quick answers

What does Teams error 403 InvalidBotApiHost mean?

Your bot called the public Bot API host for a conversation that lives in a Government Community Cloud (GCC) tenant. The status table documents InvalidBotApiHost with the message "Invalid agent api host.

How do I fix Teams error 403 InvalidBotApiHost?

1. Follow the documented retry: switch the request's base URL to https://smba.infra.gcc.teams.microsoft.com for this conversation and resend. 2. Persist serviceUrl alongside every conversation reference and always build Connector clients from it. 3. Audit the codebase for hardcoded smba hosts; keep the documented global URLs only as fallbacks per cloud. 4. Test with a GCC test tenant if government customers are in scope.

Stop debugging Teams by hand

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