diff --git a/ymt_v3_api/errors.go b/ymt_v3_api/errors.go
new file mode 100644
index 0000000..f125e81
--- /dev/null
+++ b/ymt_v3_api/errors.go
@@ -0,0 +1,42 @@
+package ymt_v3_api
+
+import "fmt"
+
+// APIError 表示 API 返回的错误信息。
+type APIError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Reason  string `json:"reason,omitempty"`
+}
+
+func (e *APIError) Error() string {
+	if e.Reason != "" {
+		return fmt.Sprintf("API error [%d]: %s (reason: %s)", e.Code, e.Message, e.Reason)
+	}
+	return fmt.Sprintf("API error [%d]: %s", e.Code, e.Message)
+}
+
+// 公共错误码常量
+const (
+	ErrCodeSystemError          = 500
+	ErrCodeInvalidPayload       = 400
+	ErrCodeMissingParam         = 400
+	ErrCodeInvalidTimestamp     = 400
+	ErrCodeDecryptFailed        = 400
+	ErrCodeAppNotFound          = 401
+	ErrCodeInvalidSignature     = 401
+	ErrCodeExpiredTimestamp     = 401
+	ErrCodeDuplicateRequest     = 429
+	ErrCodeActivityNotAuth      = 401
+	ErrCodeMerchantNotExist     = 401
+	ErrCodeMerchantNotAuth      = 401
+	ErrCodeMerchantAppIncomplete = 401
+	ErrCodeMerchantAppNotAuth   = 401
+	ErrCodeActivityExpire       = 403
+	ErrCodeActivityOutOfStock   = 403
+	ErrCodeActivityNotExist     = 404
+	ErrCodeMerchantOrderNotExist = 404
+	ErrCodeKeyNotExist          = 404
+	ErrCodeParamFail            = 400
+	ErrCodeParamDecryptFail     = 400
+)
\ No newline at end of file