> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.orderupb2b.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server.

# 欄位長度上限

客戶、商品、規格（SKU）、後台使用者的每一個字串欄位，都對應資料庫裡一個固定寬度的欄位。寫入的值超過對應的長度上限會被拒絕，但驗證的時機有一個容易忽略的細節，見下方「只檢查有送出的欄位」。

## 完整對照表

長度以字元數計算。

| 資源      | 欄位                | 長度上限 | 超過時的錯誤代碼                    |
| ------- | ----------------- | ---- | --------------------------- |
| 客戶      | `outerSysCode`    | 50   | `outer_sys_code_too_long`   |
| 客戶      | `name`            | 50   | `name_too_long`             |
| 客戶      | `shortName`       | 20   | `short_name_too_long`       |
| 客戶      | `cellPhone`       | 20   | `cell_phone_too_long`       |
| 客戶      | `shippingAddress` | 50   | `shipping_address_too_long` |
| 商品      | `outerSysCode`    | 50   | `outer_sys_code_too_long`   |
| 商品      | `name`            | 100  | `name_too_long`             |
| 規格（SKU） | `outerSysCode`    | 50   | `outer_sys_code_too_long`   |
| 規格（SKU） | `name`            | 100  | `name_too_long`             |
| 規格（SKU） | `barcode`         | 50   | `barcode_too_long`          |
| 規格（SKU） | `warehouse`       | 50   | `warehouse_too_long`        |
| 規格（SKU） | `unit`            | 50   | `unit_too_long`             |
| 規格（SKU） | `spec`            | 50   | `spec_too_long`             |
| 後台使用者   | `account`（僅建立時可送） | 50   | `account_too_long`          |
| 後台使用者   | `name`            | 30   | `name_too_long`             |
| 後台使用者   | `email`           | 100  | `email_too_long`            |
| 後台使用者   | `outerSysCode`    | 50   | `outer_sys_code_too_long`   |

## 只檢查有送出的欄位

「省略的欄位保留原值」是「Upsert 與冪等」頁講過的部分合併規則；長度驗證完全沿用同一個判斷——**一個欄位只有在你這次請求真的送出值時才會被檢查，省略的欄位一律跳過驗證**，因為省略的欄位根本不會被寫進資料庫，沒有值可以檢查。

實際看一次：假設客戶 `id=501` 目前每個欄位都是合法值，這次更新只送 `cellPhone`：

**`PUT /v1/customers/501`**

```json title="PUT /v1/customers/501"
{
  "cellPhone": "02-2345-6789"
}
```

這個請求只會檢查 `cellPhone`（上限 20 字元）；`name`、`shortName`、`shippingAddress` 完全不會被檢查，因為它們沒有出現在這次請求裡——不管它們現在的值是什麼，這次更新都不會去看，也不需要重新送一次來「通過驗證」。

這條規則也代表：**新增（create）時省略一個字串欄位，永遠不會觸發長度錯誤**，因為省略的欄位在新增時會被視為空字串（見「Upsert 與冪等」），空字串的長度是 0，不可能超過任何上限。

規格（SKU）的 `outerSysCode`／`productId` 另外各自有獨立的「必填」檢查——建立時省略會回傳 `400 outerSysCode is required to create a SKU` 或 `400 productId is required to create a SKU`（注意這兩個代碼本身不是 snake\_case，是逐字的英文句子）。必填檢查與這裡的長度檢查是兩件事：省略是必填檢查的責任，長度檢查只處理「有填但太長」。

## 超過長度會怎樣

超過對應欄位的長度上限，會回傳 `400 {field}_too_long`——`{field}` 是欄位名稱的 snake\_case 版本，例如 `outerSysCode` 對應 `outer_sys_code_too_long`，`shortName` 對應 `short_name_too_long`。每個欄位對應的實際代碼已經列在上表最後一欄。

## 下一步

#### [Upsert 與冪等](/upsert)

部分合併規則的完整說明——省略欄位為什麼會保留原值

#### [錯誤碼](/errors)

完整的錯誤代碼對照表，以及兩種錯誤回應形狀