# IT 运营 / AI Coding 用量 - 错误码

> **版本**: v0.1
> **最后更新**: 2026-05-15

---

## 错误码清单

| HTTP | code | i18n key | 触发场景 | 客户端行为 |
|------|------|----------|----------|------------|
| 401 | `AI_USAGE_INVALID_TOKEN` | `aiUsage.errors.invalid_token` | Token 不存在 / bcrypt 不匹配 / revokedAt 不为 null | 写本地日志，提示员工 `ffctk login` 重输；停止上报直到下次手动启动 |
| 403 | `AI_USAGE_DEVICE_BLOCKED` | `aiUsage.errors.device_blocked` | device.blockedAt 不为 null | 停止该 device 上报循环；本地缓冲保留；写明显告警 |
| 413 | `AI_USAGE_BATCH_TOO_LARGE` | `aiUsage.errors.batch_too_large` | events 数 > 500 或 body > 1MB | 客户端拆批重发 |
| 422 | `AI_USAGE_INVALID_PAYLOAD` | `aiUsage.errors.invalid_payload` | Body schema 校验失败 | 客户端不重试该批，写日志，进本地"问题事件"备查 |
| 429 | `AI_USAGE_RATE_LIMIT_EXCEEDED` | `aiUsage.errors.rate_limit_exceeded` | 60 req/min/token 超限 | 客户端 exponential backoff（base 2s，max 60s） |
| 403 | `AI_USAGE_FORBIDDEN` | `common.errors.forbidden` | JWT 用户无对应权限点（`view-all` 等） | 前端跳无权限页 |
| 404 | `AI_USAGE_TOKEN_NOT_FOUND` | `aiUsage.errors.token_not_found` | DELETE 不存在的 token 或非自己的 token（DataScope） | 前端 toast |
| 404 | `AI_USAGE_DEVICE_NOT_FOUND` | `aiUsage.errors.device_not_found` | block 不存在的 device | 前端 toast |
| 409 | `AI_USAGE_TOKEN_ALREADY_REVOKED` | `aiUsage.errors.token_already_revoked` | 撤销已撤销 token | 前端 toast，列表刷新 |
| 409 | `AI_USAGE_DEVICE_ALREADY_BLOCKED` | `aiUsage.errors.device_already_blocked` | 拉黑已拉黑 device | 前端 toast |
| 500 | `AI_USAGE_INGESTION_INTERNAL` | `common.errors.internal` | DB 写入失败等 | 客户端整批 retry（exponential backoff） |

---

## 客户端 retry 策略

| HTTP | 是否重试 | backoff |
|------|----------|---------|
| 401 | 否 | 暂停上报直到用户 `ffctk login` 重置 |
| 403 (device blocked) | 否 | 暂停该 device 上报 |
| 413 | 是 | 拆批后立即 |
| 422 | 否（写问题日志） | - |
| 429 | 是 | exp 2s..60s |
| 5xx | 是 | exp 2s..120s |
| 网络错误 / 超时 | 是 | exp 2s..60s |

死锁逃逸：连续 24h 失败 → 客户端写 `ffctk.log` ERROR 级 + 本地 desktop notification（macOS notification center / linux notify-send / Windows toast）告知员工"长时间未能上报，请运行 `ffctk status` 查看"。