feishu-troubleshoot

飞书Troubleshooting

FAQ (Frequently Asked Questions)

Authorization Related

Token Expired

• Symptom: API call returns 99991668 or 99991672
• Solution: Re-run the OAuth authorization flow

Insufficient Permissions

• Symptom: API returns 99991400 or 99991403
• Solution: Check whether the app has enabled the required API permissions. See the permission mapping table below

Refresh Token Expired

• Symptom: An error is returned when refreshing the token
• Solution: You need to go through the full OAuth flow again

Permission Mapping Table

Function Module	Required Permission Scope
Calendar Read/Write	calendar:calendar, calendar:calendar:readonly
Document Read/Write	docx:document, docx:document:readonly
Bitable	bitable:app, bitable:app:readonly
Task Management	task:task, task:task:readonly
Contacts	contact:user.base:readonly, contact:department.base:readonly
Message Read/Write	im:message, im:message:readonly
Cloud Drive	drive:drive, drive:drive:readonly
Wiki	wiki:wiki, wiki:wiki:readonly
Mail	mail:mailgroup, mail:mailgroup:readonly

API Call Issues

Rate Limit

• 飞书 APIs have rate limits, usually 100 requests/second
• For batch operations, it is recommended to run serially + delay 0.5-1 second

Field Value Format Error

• Refer to skills/feishu-bitable/references/record-values.md

Diagnostic Commands

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

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