集成UPS Rating API时遭遇110601无效重量错误

错误信息 #

{"response":{"errors":[{"code":"110601","message":"Missing or invalid package weight for package 1."}]}}

原始请求JSON #

{
    "RateRequest": {
      "Request": {
        "TransactionReference": {
          "CustomerContext": "CustomerContext"
        }
      },
      "Shipment": {
        "Shipper": {
          "Name": "ShipperName",
          "ShipperNumber": "123456",
          "Address": {
            "AddressLine": [
              "ShipperAddressLine",
              "ShipperAddressLine",
              "ShipperAddressLine"
            ],
            "City": "TIMONIUM",
            "StateProvinceCode": "MD",
            "PostalCode": "21093",
            "CountryCode": "US"
          }
        },
        "ShipTo": {
          "Name": "ShipToName",
          "Address": {
            "AddressLine": [
              "ShipToAddressLine",
              "ShipToAddressLine",
              "ShipToAddressLine"
            ],
            "City": "Alpharetta",
            "StateProvinceCode": "GA",
            "PostalCode": "30005",
            "CountryCode": "US"
          }
        },
        "ShipFrom": {
          "Name": "ShipFromName",
          "Address": {
            "AddressLine": [
              "ShipFromAddressLine",
              "ShipFromAddressLine",
              "ShipFromAddressLine"
            ],
            "City": "TIMONIUM",
            "StateProvinceCode": "MD",
            "PostalCode": "21093",
            "CountryCode": "US"
          }
        },
        "PaymentDetails": {
          "ShipmentCharge": {
            "Type": "01",
            "BillShipper": {
              "AccountNumber": "123456"
            }
          }
        },
        "Service": {
          "Code": "03",
          "Description": "Ground"
        },
        "NumOfPieces": "1",
        "Package": {
          "SimpleRate": {
            "Description": "SimpleRateDescription",
            "Code": "XS"
          },
          "PackagingType": {
            "Code": "02",
            "Description": "Packaging"
          },
          "Dimensions": {
            "UnitOfMeasurement": {
              "Code": "IN",
              "Description": "Inches"
            },
            "Length": "5",
            "Width": "5",
            "Height": "5"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "LBS",
              "Description": "Pounds"
            },
            "Weight": "5"
          },
          "ShipmentTotalWeight": {
            "UnitOfMeasurement": {
              "Code": "LBS",
              "Description": "Pounds"
            },
            "Weight": "5"
          }    
        }
      }
    }
  }

问题分析 #

你的请求看似包含重量字段，但触发错误的核心原因有两个：

1. SimpleRate的优先级冲突：当请求中指定了SimpleRate（如Code": "XS"），UPS API会优先尝试使用该预设费率对应的重量配置。如果你的UPS账号未开通对应SimpleRate服务，或预设重量未正确关联，API会忽略自定义的PackageWeight，导致重量缺失判断。
2. Package字段格式问题：部分UPS API版本要求，即使只有一个包裹，Package也必须是数组格式，而非单个对象，否则API无法正确解析包裹属性。

修正方案 #

方案1：移除SimpleRate，使用自定义重量 #

若无需SimpleRate服务，直接删除SimpleRate节点，让API读取PackageWeight的数值：

{
    "RateRequest": {
      "Request": {
        "TransactionReference": {
          "CustomerContext": "CustomerContext"
        }
      },
      "Shipment": {
        // 保留Shipper、ShipTo、ShipFrom等其他字段
        "Service": {
          "Code": "03",
          "Description": "Ground"
        },
        "NumOfPieces": "1",
        "Package": {
          "PackagingType": {
            "Code": "02",
            "Description": "Packaging"
          },
          "Dimensions": {
            "UnitOfMeasurement": {
              "Code": "IN",
              "Description": "Inches"
            },
            "Length": "5",
            "Width": "5",
            "Height": "5"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "LBS",
              "Description": "Pounds"
            },
            "Weight": "5"
          }
        }
      }
    }
  }

方案2：保留SimpleRate并调整格式 #

若需使用SimpleRate，先确认账号已开通对应服务，再将Package改为数组格式：

{
    "RateRequest": {
      "Request": {
        "TransactionReference": {
          "CustomerContext": "CustomerContext"
        }
      },
      "Shipment": {
        // 保留其他字段
        "Service": {
          "Code": "03",
          "Description": "Ground"
        },
        "NumOfPieces": "1",
        "Package": [
          {
            "SimpleRate": {
              "Description": "SimpleRateDescription",
              "Code": "XS"
            },
            "PackagingType": {
              "Code": "02",
              "Description": "Packaging"
            },
            "Dimensions": {
              "UnitOfMeasurement": {
                "Code": "IN",
                "Description": "Inches"
              },
              "Length": "5",
              "Width": "5",
              "Height": "5"
            },
            "PackageWeight": {
              "UnitOfMeasurement": {
                "Code": "LBS",
                "Description": "Pounds"
              },
              "Weight": "5"
            }
          }
        ]
      }
    }
  }

额外检查点 #

• 将Weight字段的字符串值（如"5"）改为数字格式5，部分API版本对数据类型有严格要求
• 确认UnitOfMeasurement的Code无拼写错误（LBS为合法英制单位）
• 验证Service代码与SimpleRate支持的服务匹配（Ground服务03兼容SimpleRate，但部分地区可能有差异）

内容的提问来源于stack exchange，提问作者Quentin Salzwedel