Troubleshooting
I see “Bearer authentication required”
Data endpoints require a personal API token in the Authorization header. A browser address-bar request does not include it. Start with the connection guide, or send a request from your API client with the header shown in the examples.
GET /health checks the service process without authenticating to Telegram. A healthy service does not mean your Telegram session is still valid.
Common responses
| Status / code | What to do |
|---|---|
401 UNAUTHORIZED | Enter a valid personal API token. An analytics API key or Telegram cookie is not a substitute. |
401 SESSION_EXPIRED | Sign in to Telegram Ads and click Replace cookies. Keep using your personal API token. |
403 FORBIDDEN | Check token scopes, API origin and the browser Origin allowlist. |
404 CONNECTION_NOT_FOUND | List your connections and use a returned ID owned by your principal. |
409 CONNECTION_VERSION_CONFLICT | Refresh the selected connection before replacing or disconnecting it. |
410 CONNECTION_DISCONNECTED | Create a new connection; the old cookies were removed. |
400 INVALID_REQUEST | Check the endpoint's schema, month format, IDs and allowed parameters. |
429 BUSY / RATE_LIMITED | Reduce concurrency and pause before retrying reads. |
502 PROTOCOL_DRIFT | Report the operation and time to the operator; the upstream response no longer matches the verified contract. |
NO_DATA | Choose a period/account with data; an empty report is not necessarily a session failure. |
Chrome does not connect
- Use the extension toolbar popup, not
index.htmlopened in a normal tab. - Ensure the API origin is exactly
https://tgads.tlmtr.dev. - Approve the requested permissions for cookies, Telegram Ads and the API host.
- Sign in to Telegram Ads in the same Chrome profile where the extension is installed.
- After Chrome restarts or you reload the extension, paste the personal token again and use Load / refresh connections.
- If you changed the API origin, supply the personal token issued for that deployment.
MCP cannot initialize
Use the connection-specific /mcp URL, Streamable HTTP and a custom Authorization header. The token needs both mcp:read and ads:read. Automatic OAuth discovery and a browser login page are not provided. Follow the SDK example to distinguish client configuration from a session error.
When asking for help, share the route name, time, HTTP status and safe error code. Keep access tokens and cookie values out of logs, chat messages and screenshots.