本文详解 Kintone Add Record API 调用中出现 CB_VA01 错误（提示“必须填写”）的常见原因，重点指出看似已赋值却仍报错的关键陷阱——空字符串 "" 被 Kintone 视为未填写，并提供可立即验证的调试方案与正确请求示例。
本文详解 kintone add record api 调用中出现 `cb_va01` 错误（提示“必须填写”）的常见原因，重点指出看似已赋值却仍报错的关键陷阱——空字符串 `""` 被 kintone 视为未填写，并提供可立即验证的调试方案与正确请求示例。
在使用 Kintone 的 Add Record API 时，即使请求体中已显式声明字段并赋值，仍可能收到如下典型错误：
{
"code": "CB_VA01",
"message": "入力内容が正しくありません。",
"errors": {
"record.名.value": {
"messages": ["必須です。"]
}
}
}该错误明确表示字段「名」未通过必填校验。但请注意：Kintone 对“必填字段”的判定逻辑极为严格——不仅拒绝 null，也拒绝空字符串 "" 和仅含空白字符（如 " "）的值。这意味着以下写法均会触发 CB_VA01：
// ❌ 全部无效：Kintone 将其视作“未填写”
"名": { "value": "" }
"名": { "value": " " }
"名": { "value": null } // JSON 中实际无法直接写 null，但程序生成时可能出错✅ 正确做法是确保 value 为非空、去首尾空格后的有效字符串：
{
"app": 123,
"record": {
"名": {
"value": "三宅" // ✅ 非空、无多余空白
}
}
}此外，请同步检查以下关键配置项（常被忽略但直接影响请求有效性）：
-
Header 必须包含：
- Content-Type: application/json（注意无空格、大小写不敏感但建议小写）
- X-Cybozu-API-Token:
（确认 Token 未过期、权限覆盖目标应用、且未误粘贴空格或换行）
App ID 必须为数字类型（非字符串）：
若 Postman 或代码中误写 "app": "123"（带引号），部分环境可能静默失败。请确保为 "app": 123。字段标识符需完全匹配：
检查 API 请求中的字段名（如 "名"）是否与 Kintone 应用设置中的「字段代码（Field Code）」一致（而非仅显示名称）。若字段代码实际为 last_name，则必须使用 "last_name": { "value": "三宅" }。
? 快速自检步骤：
- 在 Postman 中手动输入 "名": { "value": "三宅" }（避免从变量/脚本复制导致隐藏空格）；
- 使用 console.log(JSON.stringify(payload))（前端）或 print(json.dumps(payload))（Python）打印最终请求体，确认无意外空值；
- 临时将字段设为「非必填」测试——若此时成功，则 100% 确认为值校验问题。
⚠️ 注意：Kintone 不接受 undefined、null 或空字符串作为必填字段值，这是平台级强制策略，无法通过 API 参数绕过。务必在业务逻辑层做好数据清洗（如 .trim() 后判空）。
遵循以上规范后，您的 Add Record 请求即可稳定通过校验，成功创建记录。
