mastra-ai/mastra · error

Telegram ${method} failed: ${detail}

Error message

Telegram ${method} failed: ${detail}

What it means

botApiRequest is the low-level wrapper for all Telegram Bot API calls. It throws this error when the HTTP response is not ok or the JSON body has ok:false, using body.description (Telegram's human-readable error) or 'HTTP <status>' as detail. The thrown message embeds the method name (e.g. getMe, sendMessage) plus the detail, and transport errors (timeout/network) are thrown separately with isTransportError set.

Source

Thrown at channels/telegram/src/telegram-client.ts:50

      ? undefined
      : { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload) };
  let response: Response;
  try {
    response = await fetch(`${apiBaseUrl}/bot${botToken}/${method}`, {
      ...init,
      signal: AbortSignal.timeout(10_000),
    });
  } catch (cause) {
    // Tag transport/timeout failures so callers can tell them apart from an
    // `ok: false` API response (see getMe).
    throw Object.assign(new Error(`Telegram ${method} request failed`, { cause }), {
      isTransportError: true,
    });
  }
  const body = (await response.json().catch(() => null)) as TelegramApiResponse<TResult> | null;
  if (!response.ok || !body?.ok) {
    const detail = body?.description ?? `HTTP ${response.status}`;
    throw new Error(`Telegram ${method} failed: ${detail}`);
  }
  return body.result as TResult;
}

/**
 * Validate a bot token via `getMe` and resolve the bot's identity. Throws if
 * the token is rejected or the returned user is not a bot.
 *
 * @see https://core.telegram.org/bots/api#getme
 */
export async function getMe(botToken: string, apiBaseUrl: string = TELEGRAM_API_BASE_URL): Promise<TelegramUser> {
  let result: TelegramUser;
  try {
    result = await botApiRequest<TelegramUser>(botToken, 'getMe', apiBaseUrl);
  } catch (cause) {
    // A transport/timeout failure is a connectivity problem, not a token
    // rejection — surface it as-is rather than mislabeling it as a bad token.
    if (cause instanceof Error && (cause as { isTransportError?: boolean }).isTransportError) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the detail in the message (e.g. 'Unauthorized', 'chat not found') and fix the corresponding input — most commonly validate the bot token with getMe.
2. If the token is invalid, regenerate it via @BotFather and update the stored installation.
3. Respect Telegram rate limits — back off and retry on 429 using retry_after.
4. For 5xx, retry with backoff; check https://telegram.org/status for outages.

Example fix

// before
await client.sendMessage({ chat_id, text }); // throws on 'chat not found'
// after
try {
  await client.sendMessage({ chat_id, text });
} catch (e) {
  if (String(e.message).includes('429')) await sleep(retryAfter);
  else if (String(e.message).includes('Unauthorized')) await revalidateToken();
  else throw e;
}

const me = await getMe(botToken); // validate token before other calls; throws 'rejected the bot token' if bad
if (!me.is_bot) throw new Error('Not a bot token');

try {
  await client.sendMessage({ chat_id, text });
} catch (e) {
  const msg = e instanceof Error ? e.message : String(e);
  if (msg.includes('429') || msg.includes('Too Many Requests')) {
    await sleep(backoff); return retry();
  }
  if (msg.includes('5')) throw e; // 5xx: retry later
  throw e; // 4xx: fix input (chat_id, token, permissions)
}

When it happens

Trigger: Any Telegram Bot API call where Slack—rather Telegram returns a non-2xx status or { ok: false, description: ... }: invalid bot token (401 Unauthorized), chat not found (400), rate limit (429), or Telegram 5xx.

Common situations: Storing/entering a revoked or typo'd bot token; sending messages to a chat the bot isn't a member of; hitting rate limits during bulk sends; Telegram API incidents.

Related errors

• request failed with status ${response.status}: ${responseTex
• Perplexity Search request failed with status ${response.stat
• Failed to fetch Copilot models: ${response.status} ${respons
• Invalid Copilot models response: missing `data` array
• Failed to list projects (${res.status})

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/d3658f949a25f16b. Report an issue: GitHub.