feat(errors): map MTProto RPC errors to Bot API errors

asAPIError normalizes tgerr.Error into a Bot-API-shaped *Error: flood waits
become 429 with retry_after, and the common types (chat/message not found,
blocked/deactivated user, channel private, not-modified, ...) get Bot API
codes and descriptions. nil, existing *Error and non-RPC errors pass through
unchanged. Full table lands in Phase 6.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

errors_map.go

@@ -0,0 +1,69 @@
+package botapi
+
+import (
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/gotd/td/tgerr"
+)
+
+// 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
+	}
+	var already *Error
+	if errors.As(err, &already) {
+		return err
+	}
+	rpcErr, ok := tgerr.As(err)
+	if !ok {
+		return err
+	}
+
+	// Flood wait maps to 429 with a retry hint.
+	if d, ok := tgerr.AsFloodWait(err); ok {
+		return &Error{
+			Code:        http.StatusTooManyRequests,
+			Description: "Too Many Requests: retry later",
+			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"
+	default:
+		if out.Description == "" {
+			out.Description = http.StatusText(out.Code)
+		}
+	}
+	return out
+}

errors_map_test.go

@@ -0,0 +1,52 @@
+package botapi
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/gotd/td/tgerr"
+)
+
+func TestAsAPIError(t *testing.T) {
+	t.Run("Nil", func(t *testing.T) {
+		if asAPIError(nil) != nil {
+			t.Fatal("nil should stay nil")
+		}
+	})
+	t.Run("PassThroughNonRPC", func(t *testing.T) {
+		if got := asAPIError(context.Canceled); !errors.Is(got, context.Canceled) {
+			t.Fatalf("non-RPC error should pass through, got %v", got)
+		}
+	})
+	t.Run("AlreadyAPIError", func(t *testing.T) {
+		in := &Error{Code: 400, Description: "x"}
+		if got := asAPIError(in); got != error(in) {
+			t.Fatalf("existing *Error should be returned unchanged, got %v", got)
+		}
+	})
+	t.Run("FloodWait", func(t *testing.T) {
+		got := asAPIError(&tgerr.Error{Code: 420, Type: "FLOOD_WAIT", Argument: 12})
+		var apiErr *Error
+		if !errors.As(got, &apiErr) || apiErr.Code != 429 {
+			t.Fatalf("want 429, got %#v", got)
+		}
+		if apiErr.Parameters == nil || apiErr.Parameters.RetryAfter != 12 {
+			t.Fatalf("want retry_after=12, got %#v", apiErr.Parameters)
+		}
+	})
+	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)
+		}
+	})
+	t.Run("ChatNotFound", func(t *testing.T) {
+		got := asAPIError(&tgerr.Error{Code: 400, Type: "PEER_ID_INVALID"})
+		var apiErr *Error
+		if !errors.As(got, &apiErr) || apiErr.Code != 400 || apiErr.Description != "Bad Request: chat not found" {
+			t.Fatalf("unexpected: %#v", got)
+		}
+	})
+}