错误提示要回答什么
自助平台的使用者多数不懂内部编排，看到「操作失败」只会来问客服。好的提示把内部错误翻译成用户动作，包含三要素：原因（哪个字段、哪条规则、哪个配额）、影响（申请是否已受理、会不会自动重试）、下一步（改什么、找谁）。它是自助率的关键指标，而不是装饰性文案。
基本信息
| 面向对象 | 申请人（非专业）、运维（排障）、客服（传话） |
|---|---|
| 三要素 | 原因、影响范围、下一步动作 |
| 必备字段 | 错误码、用户可读文案、request_id、发生时间 |
| 分级方式 | 参数类、配额类、权限类、依赖缺失类、系统类 |
| 语气要求 | 陈述事实并给出动作，不指责用户 |
典型使用场景
- 表单校验失败：明确指出字段名与规则，让用户当场改完重提
- 配额不足：给出剩余量、申请量与提升途径，而不是只报失败
- 权限不足：说明缺哪个角色、由谁分配，降低工单量
- 依赖资源缺失：指出前置资源已删除或不可用，并给出重建路径
- 下游超时：告知任务已受理、将自动重试，可用任务号查询进度
错误类别与文案要点
| 错误类别 | 提示重点 | 文案要点 |
|---|---|---|
| 参数校验 | 哪个字段、违反哪条规则、正确格式 | 「到期时间需晚于当前时间」 |
| 配额不足 | 剩余量、申请量、提升途径 | 「本租户剩余 2 核，本次需 4 核，请联系管理员调整配额」 |
| 权限不足 | 缺少的角色与分配人 | 「当前角色无审批权限，请联系本租户管理员」 |
| 依赖缺失 | 哪个前置资源不可用、如何补 | 「所选网络已删除，请重新选择后提交」 |
| 系统与下游错误 | 已受理状态、是否自动重试、查询入口 | 「交付任务已排队，可在任务列表查看进度」 |
统一错误结构
统一错误结构
{
"code": "QUOTA_CPU_INSUFFICIENT", // 稳定错误码，便于前端与监控聚合
"message": "本租户剩余 2 核，本次申请需 4 核", // 用户可读，不带内部术语
"suggest": "联系本租户管理员调整配额后重试", // 明确的下一步动作
"request_id": "req-7f3a91", // 用户界面与后台日志同值，客服凭它定位
"retriable": true // 前端据此决定是否展示重试按钮
}同一 request_id 必须同时出现在用户界面与平台日志中，否则客服拿到截图也无法定位；错误码要稳定且可聚合，文案可随版本改而不破坏监控口径。
不要把堆栈、SQL 语句、内网 IP、云厂商原始报错直接回显给前端：既是信息泄露面，也让用户无从下手。完整细节写日志，前端只给分类结论与动作。