feat(errors): comprehensive tgerr -> Bot API error mapping

ernado · claude · ernado · commit a9e5e0e1b24e · 2026-06-13T22:14:25.000+03:00
Replace the small switch with a ~50-entry table mirroring the official
telegram-bot-api server (Client.cpp fail_query_with_error + TDLib send
rewrites), plus the server's code-normalization (sub-400/404 -&gt; 400,
SCREAMING_CASE 403 -&gt; 400) and prefix/casing fallback for unmapped
errors. Add AsChatMigrated and Code helpers alongside AsFloodWait.

Studied /src/telegram/telegram-bot-api for the authoritative mappings.

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/errors.go b/errors.go
@@ -63,3 +63,23 @@ func AsFloodWait(err error) (retryAfter time.Duration, ok bool) {
 	}
 	return tgerr.AsFloodWait(err)
 }
+
+// AsChatMigrated reports whether err indicates that a basic group was upgraded
+// to a supergroup and, if so, the new supergroup chat id the caller should use.
+func AsChatMigrated(err error) (newChatID int64, ok bool) {
+	var apiErr *Error
+	if errors.As(err, &apiErr) && apiErr.Parameters != nil && apiErr.Parameters.MigrateToChatID != 0 {
+		return apiErr.Parameters.MigrateToChatID, true
+	}
+	return 0, false
+}
+
+// Code returns the Bot API error code carried by err, or 0 if err is not a
+// *Error. It is a convenience over errors.As for the common branch-on-code case.
+func Code(err error) int {
+	var apiErr *Error
+	if errors.As(err, &apiErr) {
+		return apiErr.Code
+	}
+	return 0
+}
diff --git a/errors_map.go b/errors_map.go
@@ -3,18 +3,115 @@ package botapi
 import (
 	"errors"
 	"net/http"
+	"strconv"
 	"time"
 
 	"github.com/gotd/td/tgerr"
 )
 
+// Shared Bot API error descriptions reused across the mapping and the methods.
+const (
+	descChatNotFound = "Bad Request: chat not found"
+	descWrongFileID  = "Bad Request: wrong file identifier/HTTP URL specified"
+	descUnauthorized = "Unauthorized"
+
+	descNotModified = "Bad Request: message is not modified: specified new message content " +
+		"and reply markup are exactly the same as a current content and reply markup of the message"
+	descPhotoExt = "Bad Request: Photo has unsupported extension. " +
+		"Use one of .jpg, .jpeg, .gif, .png, .tif or .bmp"
+)
+
+// rpcMapping is the final Bot API code and description for a known MTProto RPC
+// error type. Descriptions are the verbatim strings the official Bot API server
+// returns (including their "Bad Request:"/"Forbidden:" prefix), so callers see
+// behavior identical to the HTTP Bot API.
+type rpcMapping struct {
+	code int
+	desc string
+}
+
+// rpcErrorMap translates MTProto RPC error types into Bot API errors. It mirrors
+// the official telegram-bot-api server (Client.cpp fail_query_with_error and the
+// TDLib send-error rewrites). Where the official description depends on the
+// calling method (e.g. "message to edit not found"), a method-independent
+// wording is used since asAPIError has no method context.
+var rpcErrorMap = map[string]rpcMapping{
+	// Chat / peer resolution.
+	"PEER_ID_INVALID":       {http.StatusBadRequest, descChatNotFound},
+	"CHAT_ID_INVALID":       {http.StatusBadRequest, descChatNotFound},
+	"CHAT_NOT_FOUND":        {http.StatusBadRequest, descChatNotFound},
+	"CHANNEL_INVALID":       {http.StatusBadRequest, descChatNotFound},
+	"USERNAME_INVALID":      {http.StatusBadRequest, descChatNotFound},
+	"USERNAME_NOT_OCCUPIED": {http.StatusBadRequest, descChatNotFound},
+	"USER_ID_INVALID":       {http.StatusBadRequest, "Bad Request: user not found"},
+
+	// Messages.
+	"MESSAGE_ID_INVALID":       {http.StatusBadRequest, "Bad Request: message to be edited not found"},
+	"MESSAGE_NOT_MODIFIED":     {http.StatusBadRequest, descNotModified},
+	"MESSAGE_EMPTY":            {http.StatusBadRequest, "Bad Request: message text is empty"},
+	"MESSAGE_TOO_LONG":         {http.StatusBadRequest, "Bad Request: message is too long"},
+	"MEDIA_CAPTION_TOO_LONG":   {http.StatusBadRequest, "Bad Request: message caption is too long"},
+	"MESSAGE_DELETE_FORBIDDEN": {http.StatusBadRequest, "Bad Request: message can't be deleted"},
+	"MESSAGE_AUTHOR_REQUIRED":  {http.StatusBadRequest, "Bad Request: message can't be edited"},
+
+	// Reply markup / buttons.
+	"REPLY_MARKUP_TOO_LONG": {http.StatusBadRequest, "Bad Request: reply markup is too long"},
+	"REPLY_MARKUP_INVALID":  {http.StatusBadRequest, "Bad Request: reply markup is invalid"},
+	"BUTTON_URL_INVALID":    {http.StatusBadRequest, "Bad Request: button URL is invalid"},
+	"BUTTON_DATA_INVALID":   {http.StatusBadRequest, "Bad Request: button data is invalid"},
+
+	// URLs / web pages / media.
+	"WC_CONVERT_URL_INVALID":   {http.StatusBadRequest, "Bad Request: Wrong HTTP URL specified"},
+	"EXTERNAL_URL_INVALID":     {http.StatusBadRequest, "Bad Request: Wrong HTTP URL specified"},
+	"WEBPAGE_CURL_FAILED":      {http.StatusBadRequest, "Bad Request: Failed to get HTTP URL content"},
+	"WEBPAGE_MEDIA_EMPTY":      {http.StatusBadRequest, "Bad Request: Wrong type of the web page content"},
+	"MEDIA_GROUPED_INVALID":    {http.StatusBadRequest, "Bad Request: Can't use the media of the specified type in the album"},
+	"MEDIA_EMPTY":              {http.StatusBadRequest, "Bad Request: Wrong file identifier/HTTP URL specified"},
+	"PHOTO_EXT_INVALID":        {http.StatusBadRequest, descPhotoExt},
+	"PHOTO_INVALID_DIMENSIONS": {http.StatusBadRequest, "Bad Request: PHOTO_INVALID_DIMENSIONS"},
+	"FILE_PARTS_INVALID":       {http.StatusBadRequest, "Bad Request: file is too big"},
+	"FILE_REFERENCE_EXPIRED":   {http.StatusBadRequest, descWrongFileID},
+
+	// Inline / callback queries.
+	"QUERY_ID_INVALID": {http.StatusBadRequest, "Bad Request: query is too old and response timeout expired or query ID is invalid"},
+
+	// Stickers.
+	"PACK_SHORT_NAME_INVALID":  {http.StatusBadRequest, "Bad Request: invalid sticker set name is specified"},
+	"PACK_SHORT_NAME_OCCUPIED": {http.StatusBadRequest, "Bad Request: sticker set name is already occupied"},
+	"STICKER_EMOJI_INVALID":    {http.StatusBadRequest, "Bad Request: invalid sticker emojis"},
+	"STICKERSET_INVALID":       {http.StatusBadRequest, "Bad Request: STICKERSET_INVALID"},
+
+	// Chat description / about.
+	"CHAT_ABOUT_NOT_MODIFIED": {http.StatusBadRequest, "Bad Request: chat description is not modified"},
+
+	// Member management.
+	"USER_ADMIN_INVALID":      {http.StatusBadRequest, "Bad Request: user is an administrator of the chat"},
+	"CHAT_ADMIN_REQUIRED":     {http.StatusBadRequest, "Bad Request: not enough rights"},
+	"USER_NOT_PARTICIPANT":    {http.StatusBadRequest, "Bad Request: user is not a member of the chat"},
+	"USER_NOT_MUTUAL_CONTACT": {http.StatusBadRequest, "Bad Request: user is not a mutual contact"},
+	"ADMINS_TOO_MUCH":         {http.StatusBadRequest, "Bad Request: there are too many administrators in the chat"},
+	"USER_CHANNELS_TOO_MUCH":  {http.StatusBadRequest, "Bad Request: the user is a member of too many chats"},
+
+	// Forbidden (403) cases.
+	"INPUT_USER_DEACTIVATED":    {http.StatusForbidden, "Forbidden: user is deactivated"},
+	"USER_IS_BLOCKED":           {http.StatusForbidden, "Forbidden: bot was blocked by the user"},
+	"USER_IS_BOT":               {http.StatusForbidden, "Forbidden: bot can't send messages to bots"},
+	"USER_DELETED":              {http.StatusForbidden, "Forbidden: user is deactivated"},
+	"CHAT_WRITE_FORBIDDEN":      {http.StatusForbidden, "Forbidden: bot can't send messages to the chat"},
+	"CHAT_SEND_MEDIA_FORBIDDEN": {http.StatusForbidden, "Forbidden: not enough rights to send media to the chat"},
+	"CHANNEL_PRIVATE":           {http.StatusForbidden, "Forbidden: bot is not a member of the chat"},
+	"BOT_GROUPS_BLOCKED":        {http.StatusForbidden, "Forbidden: bot can't be added to groups"},
+
+	// Auth.
+	"AUTH_KEY_UNREGISTERED": {http.StatusUnauthorized, descUnauthorized},
+	"SESSION_REVOKED":       {http.StatusUnauthorized, descUnauthorized},
+	"USER_DEACTIVATED":      {http.StatusUnauthorized, descUnauthorized},
+}
+
 // asAPIError normalizes an error from the MTProto layer into a Bot-API-shaped
 // *Error. It is a no-op for nil, for errors that are already *Error, and for
 // non-RPC errors (e.g. context cancellation or network failures), which are
 // returned unchanged so callers can branch on them.
-//
-// The mapping here covers the common cases; the full tgerr -> Bot API table is
-// completed in Phase 6.
 func asAPIError(err error) error {
 	if err == nil {
 		return nil
@@ -32,38 +129,94 @@ func asAPIError(err error) error {
 	if d, ok := tgerr.AsFloodWait(err); ok {
 		return &Error{
 			Code:        http.StatusTooManyRequests,
-			Description: "Too Many Requests: retry later",
+			Description: "Too Many Requests: retry after " + strconv.Itoa(int(d/time.Second)),
 			Parameters:  &ResponseParameters{RetryAfter: int(d / time.Second)},
 			err:         err,
 		}
 	}
 
-	out := &Error{Code: rpcErr.Code, Description: rpcErr.Message, err: err}
-	switch rpcErr.Type {
-	case "PEER_ID_INVALID", "CHAT_ID_INVALID", "CHAT_NOT_FOUND":
-		out.Code, out.Description = http.StatusBadRequest, "Bad Request: chat not found"
-	case "MESSAGE_ID_INVALID", "MESSAGE_NOT_FOUND":
-		out.Code, out.Description = http.StatusBadRequest, "Bad Request: message not found"
-	case "MESSAGE_NOT_MODIFIED":
-		out.Code = http.StatusBadRequest
-		out.Description = "Bad Request: message is not modified: specified new message content " +
-			"and reply markup are exactly the same as a current content and reply markup of the message"
-	case "MESSAGE_EMPTY":
-		out.Code, out.Description = http.StatusBadRequest, "Bad Request: message text is empty"
-	case "REPLY_MARKUP_TOO_LONG":
-		out.Code, out.Description = http.StatusBadRequest, "Bad Request: reply markup is too long"
-	case "USER_IS_BLOCKED":
-		out.Code, out.Description = http.StatusForbidden, "Forbidden: bot was blocked by the user"
-	case "INPUT_USER_DEACTIVATED":
-		out.Code, out.Description = http.StatusForbidden, "Forbidden: user is deactivated"
-	case "CHANNEL_PRIVATE":
-		out.Code, out.Description = http.StatusForbidden, "Forbidden: bot is not a member of the chat"
-	case "USER_ADMIN_INVALID":
-		out.Code, out.Description = http.StatusBadRequest, "Bad Request: user is an administrator of the chat"
+	if m, ok := rpcErrorMap[rpcErr.Type]; ok {
+		return &Error{Code: m.code, Description: m.desc, err: err}
+	}
+
+	// Unknown error: apply the official server's normalization and prefix rules.
+	code := normalizeErrorCode(rpcErr.Code, rpcErr.Message)
+	return &Error{
+		Code:        code,
+		Description: prefixDescription(code, rpcErr.Message),
+		err:         err,
+	}
+}
+
+// normalizeErrorCode mirrors the official server's code remapping: codes below
+// 400 (and 404) collapse to 400, and a 403 whose message is a bare SCREAMING_CASE
+// RPC constant is downgraded to 400.
+func normalizeErrorCode(code int, message string) int {
+	if code < http.StatusBadRequest || code == http.StatusNotFound {
+		return http.StatusBadRequest
+	}
+	if code == http.StatusForbidden && isScreamingCase(message) {
+		return http.StatusBadRequest
+	}
+	return code
+}
+
+// prefixDescription prepends the Bot API status prefix to a raw error message,
+// following the official casing rule: a SCREAMING_CASE constant is kept verbatim,
+// otherwise the first letter is lowercased.
+func prefixDescription(code int, message string) string {
+	prefix := statusPrefix(code)
+	if message == "" {
+		return prefix
+	}
+	if hasPrefix(message, prefix) {
+		return message
+	}
+	if len(message) >= 2 && (message[1] == '_' || isUpper(message[1])) {
+		return prefix + ": " + message
+	}
+	return prefix + ": " + lowerFirst(message)
+}
+
+// statusPrefix returns the Bot API description prefix for a status code. Unknown
+// codes use the 400 prefix (matching the official server's default branch).
+func statusPrefix(code int) string {
+	switch code {
+	case http.StatusUnauthorized:
+		return "Unauthorized"
+	case http.StatusForbidden:
+		return "Forbidden"
+	case http.StatusInternalServerError:
+		return "Internal Server Error"
 	default:
-		if out.Description == "" {
-			out.Description = http.StatusText(out.Code)
+		return "Bad Request"
+	}
+}
+
+func isScreamingCase(s string) bool {
+	if s == "" {
+		return false
+	}
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		if !(c >= 'A' && c <= 'Z') && !(c >= '0' && c <= '9') && c != '_' {
+			return false
 		}
 	}
-	return out
+	return true
+}
+
+func isUpper(c byte) bool { return c >= 'A' && c <= 'Z' }
+
+func hasPrefix(s, prefix string) bool {
+	return len(s) >= len(prefix) && s[:len(prefix)] == prefix
+}
+
+func lowerFirst(s string) string {
+	if s == "" || !isUpper(s[0]) {
+		return s
+	}
+	b := []byte(s)
+	b[0] += 'a' - 'A'
+	return string(b)
 }
diff --git a/errors_map_test.go b/errors_map_test.go
@@ -34,13 +34,19 @@ func TestAsAPIError(t *testing.T) {
 		if apiErr.Parameters == nil || apiErr.Parameters.RetryAfter != 12 {
 			t.Fatalf("want retry_after=12, got %#v", apiErr.Parameters)
 		}
+		if apiErr.Description != "Too Many Requests: retry after 12" {
+			t.Fatalf("description: %q", apiErr.Description)
+		}
 	})
 	t.Run("Forbidden", func(t *testing.T) {
 		got := asAPIError(&tgerr.Error{Code: 400, Type: "USER_IS_BLOCKED"})
 		var apiErr *Error
 		if !errors.As(got, &apiErr) || apiErr.Code != 403 {
 			t.Fatalf("USER_IS_BLOCKED should map to 403, got %#v", got)
 		}
+		if apiErr.Description != "Forbidden: bot was blocked by the user" {
+			t.Fatalf("description: %q", apiErr.Description)
+		}
 	})
 	t.Run("ChatNotFound", func(t *testing.T) {
 		got := asAPIError(&tgerr.Error{Code: 400, Type: "PEER_ID_INVALID"})
@@ -50,3 +56,71 @@ func TestAsAPIError(t *testing.T) {
 		}
 	})
 }
+
+func TestAsAPIErrorFallback(t *testing.T) {
+	t.Run("ScreamingCaseKeptVerbatim", func(t *testing.T) {
+		got := asAPIError(&tgerr.Error{Code: 400, Type: "SOME_NEW_ERROR", Message: "SOME_NEW_ERROR"})
+		var apiErr *Error
+		if !errors.As(got, &apiErr) {
+			t.Fatal("want *Error")
+		}
+		if apiErr.Description != "Bad Request: SOME_NEW_ERROR" {
+			t.Fatalf("description: %q", apiErr.Description)
+		}
+	})
+	t.Run("Forbidden403AllCapsDowngradesTo400", func(t *testing.T) {
+		got := asAPIError(&tgerr.Error{Code: 403, Type: "MYSTERY_FORBIDDEN", Message: "MYSTERY_FORBIDDEN"})
+		if Code(got) != 400 {
+			t.Fatalf("all-caps 403 should downgrade to 400, got %d", Code(got))
+		}
+	})
+	t.Run("SubFourHundredCollapsesTo400", func(t *testing.T) {
+		got := asAPIError(&tgerr.Error{Code: 303, Type: "SEE_OTHER", Message: "Something happened"})
+		var apiErr *Error
+		if !errors.As(got, &apiErr) || apiErr.Code != 400 {
+			t.Fatalf("want 400, got %#v", got)
+		}
+		// Non-screaming message has its first letter lowercased.
+		if apiErr.Description != "Bad Request: something happened" {
+			t.Fatalf("description: %q", apiErr.Description)
+		}
+	})
+	t.Run("Genuine403WithProseKept", func(t *testing.T) {
+		got := asAPIError(&tgerr.Error{Code: 403, Type: "X", Message: "Have no rights"})
+		var apiErr *Error
+		if !errors.As(got, &apiErr) || apiErr.Code != 403 {
+			t.Fatalf("prose 403 should stay 403, got %#v", got)
+		}
+		if apiErr.Description != "Forbidden: have no rights" {
+			t.Fatalf("description: %q", apiErr.Description)
+		}
+	})
+}
+
+func TestErrorPredicates(t *testing.T) {
+	t.Run("AsFloodWait", func(t *testing.T) {
+		err := asAPIError(&tgerr.Error{Code: 420, Type: "FLOOD_WAIT", Argument: 7})
+		d, ok := AsFloodWait(err)
+		if !ok || d.Seconds() != 7 {
+			t.Fatalf("AsFloodWait: %v %v", d, ok)
+		}
+	})
+	t.Run("AsChatMigrated", func(t *testing.T) {
+		err := &Error{Code: 400, Parameters: &ResponseParameters{MigrateToChatID: -100123}}
+		id, ok := AsChatMigrated(err)
+		if !ok || id != -100123 {
+			t.Fatalf("AsChatMigrated: %v %v", id, ok)
+		}
+		if _, ok := AsChatMigrated(context.Canceled); ok {
+			t.Fatal("non-migrate error should report false")
+		}
+	})
+	t.Run("Code", func(t *testing.T) {
+		if Code(&Error{Code: 403}) != 403 {
+			t.Fatal("Code should extract 403")
+		}
+		if Code(context.Canceled) != 0 {
+			t.Fatal("Code of non-*Error should be 0")
+		}
+	})
+}
diff --git a/media.go b/media.go
@@ -42,7 +42,7 @@ func (b *Bot) photoMedia(ctx context.Context, file InputFile, caption []styling.
 	case InputFileID:
 		fid, err := fileid.DecodeFileID(string(f))
 		if err != nil {
-			return nil, &Error{Code: 400, Description: "Bad Request: wrong file identifier/HTTP URL specified"}
+			return nil, &Error{Code: 400, Description: descWrongFileID}
 		}
 		photo := &tg.InputMediaPhoto{ID: &tg.InputPhoto{
 			ID:            fid.ID,
@@ -71,7 +71,7 @@ func (b *Bot) documentMedia(ctx context.Context, file InputFile, caption []styli
 	case InputFileID:
 		fid, err := fileid.DecodeFileID(string(f))
 		if err != nil {
-			return nil, &Error{Code: 400, Description: "Bad Request: wrong file identifier/HTTP URL specified"}
+			return nil, &Error{Code: 400, Description: descWrongFileID}
 		}
 		doc := &tg.InputMediaDocument{ID: &tg.InputDocument{
 			ID:            fid.ID,
