# Feishu Troubleshoot

> When 飞书 plugin errors or auth failures occur → troubleshoot with FAQ and authorization diagnostics.

- Skill: `cklxx/feishu-troubleshoot` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cklxx/feishu-troubleshoot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cklxx/feishu-troubleshoot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cklxx (https://skillmd.com/u/cklxx)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/cklxx/feishu-troubleshoot

---


# 飞书问题排查

## 常见问题（FAQ）

### 授权相关

**Token 过期**
- 现象：API 调用返回 `99991668` 或 `99991672`
- 解决：重新执行 OAuth 授权流程

**权限不足**
- 现象：API 返回 `99991400` 或 `99991403`
- 解决：检查应用是否开通了所需的 API 权限，参考下方权限对照表

**Refresh Token 过期**
- 现象：刷新 token 时返回错误
- 解决：需要重新走完整 OAuth 流程

### 权限对照表

| 功能模块 | 所需权限 scope |
|---------|---------------|
| 日历读写 | `calendar:calendar`, `calendar:calendar:readonly` |
| 文档读写 | `docx:document`, `docx:document:readonly` |
| 多维表格 | `bitable:app`, `bitable:app:readonly` |
| 任务管理 | `task:task`, `task:task:readonly` |
| 通讯录 | `contact:user.base:readonly`, `contact:department.base:readonly` |
| 消息读写 | `im:message`, `im:message:readonly` |
| 云盘 | `drive:drive`, `drive:drive:readonly` |
| Wiki | `wiki:wiki`, `wiki:wiki:readonly` |
| 邮件 | `mail:mailgroup`, `mail:mailgroup:readonly` |

### API 调用问题

**频率限制**
- 飞书 API 有频率限制，通常 100 次/秒
- 批量操作建议串行 + 延迟 0.5-1 秒

**字段值格式错误**
- 参考 `skills/feishu-bitable/references/record-values.md`

## 诊断命令

```bash
# 查看授权状态
python3 skills/feishu-cli/run.py '{"action":"auth","subcommand":"status"}'

# 查看可用模块
python3 skills/feishu-cli/run.py '{"action":"help","topic":"modules"}'
```