错误码速查

AiWma API 在出错时统一返回结构化的 JSON 错误响应，包含机器可读的 error.code 字段。本页列出所有错误码及对应处理建议。

错误响应格式

所有错误响应遵循统一格式：

        json错误响应标准格式
        {
  "success": false,
  "error": {
    "code":    "SESSION_NOT_FOUND",      // 错误码（本页的查询 key）
    "message": "Session not found",      // 英文描述（供开发者调试）
    "details": {                         // 可选：额外上下文信息
      "sessionId": "sess_01HXYZ..."
    }
  },
  "meta": {
    "requestId": "req_01HXYZ...",        // 本次请求 ID（联系支持时提供）
    "traceId":   "tr_abc123...",         // 分布式追踪 ID
    "timestamp": "2026-05-28T08:00:00Z"
  }
}

💡

遇到问题时，请提供 requestId 和 traceId

联系 AiWma 技术支持时，附上响应中的 meta.requestId 和 meta.traceId，可以帮助我们在几分钟内定位问题根因。

4xx — 客户端错误

401 — 认证失败

错误码	描述	处理建议
`AUTH_INVALID_KEY`	API Key 无效或已吊销	检查 Key 格式，确认未被撤销
`AUTH_KEY_EXPIRED`	API Key 已超过有效期	联系 AiWma 申请新 Key
`AUTH_ENV_MISMATCH`	Key 环境与请求端点不匹配	开发 Key 只能用于开发端点，生产 Key 同理
`AUTH_MISSING_HEADER`	请求头中缺少 `X-Api-Key`	确保所有请求都包含 `X-Api-Key` Header

403 — 权限不足

错误码	描述	处理建议
`SESSION_ACCESS_DENIED`	试图访问属于其他客户的会话	每个客户只能访问自己名下的会话
`SERVICE_NOT_ENABLED`	当前套餐未开通该服务（如 AIJ）	联系 AiWma 升级套餐或开通对应服务
`INTERVIEW_TYPE_NOT_ALLOWED`	当前套餐不允许使用该采访类型	检查配置文件中 `aij.interviewTypes` 的设置

404 — 资源不存在

错误码	描述	处理建议
`SESSION_NOT_FOUND`	指定的会话 ID 不存在	确认 Session ID 格式正确（UUID v4）
`INTERVIEW_NOT_FOUND`	指定的采访 ID 不存在	确认 Interview ID 正确，且未被删除
`DRAFT_NOT_FOUND`	草稿尚未生成或已被清理	采访结束后草稿生成需要约 30–120 秒，请稍等后重试
`CLIENT_NOT_FOUND`	API Key 对应的客户不存在	通常意味着 Key 无效，联系 AiWma 支持

409 — 状态冲突

错误码	描述	处理建议
`SESSION_ALREADY_ENDED`	对已结束的会话发送消息	检查会话状态后再发送，或创建新会话
`INTERVIEW_STATE_INVALID`	操作与当前采访状态不兼容	获取当前采访状态，按状态机规则操作
`CONSENT_NOT_GIVEN`	受访者未提供知情同意，无法发布草稿	确认采访流程中知情同意已完成

422 — 请求参数错误

错误码	描述	处理建议
`VALIDATION_FAILED`	请求体字段校验失败	查看 `details` 字段获取具体校验错误信息
`CHANNEL_INVALID`	`channel` 字段值不在允许列表内	使用 `web_widget`、`api_direct` 或 `phone`
`CONTENT_TOO_LONG`	消息内容超过最大长度（2000 字符）	拆分长消息后分多次发送

429 — 速率/配额限制

错误码	描述	处理建议
`RATE_LIMIT_EXCEEDED`	超过每分钟 API 调用限制	查看 `Retry-After` Header，等待后重试
`SESSION_QUOTA_EXCEEDED`	月会话配额已耗尽	等待下月配额重置，或联系升级套餐
`CONCURRENT_SESSION_LIMIT`	当前并发会话数达到上限	等待现有会话结束，或升级至更高并发套餐

5xx — 服务端错误

错误码	HTTP	描述	处理建议
`LLM_UNAVAILABLE`	503	主 LLM 服务不可用，备用切换失败	稍后重试（通常 30 秒内恢复）；订阅状态页获取通知
`ASR_UNAVAILABLE`	503	语音识别服务不可用	同上；系统会自动尝试本地备用 ASR
`ENGINE_INTERNAL_ERROR`	500	对话引擎内部异常	提供 `requestId` 联系支持
`CONFIG_LOAD_FAILED`	500	客户配置加载失败	检查配置文件格式，联系 AiWma 支持
`DATABASE_ERROR`	503	数据库暂时不可用	稍后重试，订阅状态页

ℹ️

5xx 错误建议实现自动重试

所有 5xx 错误都是临时性的，建议在客户端实现带退避的自动重试（最多 3 次）。唯一的例外是 CONFIG_LOAD_FAILED——这通常需要人工介入修复配置。