SuperAPI AI 工具集

error-handling

通用与其它

查看项目

更新于 10-16 08:49

技能介绍

用途:设计 API 错误码和错误响应结构,建立错误码体系,并给出调用方错误处理指南,兼顾调试与可观测性。参考 RFC 7807 Problem Details 及 Stripe、GitHub API 错误规范。

主要能力与要点:区分 HTTP 状态码(协议层:400/401/403/404/409/422/429 等)与业务错误码(业务层细化原因);错误需能指导调用方恢复,不返回 200 包装错误,不泄露内部架构。推荐简化结构含 code、message、trace_id 及可选 details;RFC 7807 标准结构含 type、title、status、detail、instance,可附加 code、trace_id、errors。错误码用 snake_case,长度 ≤30 字符,结构为 [资源]_[原因] 或 [原因],如 insufficient_funds、order_not_found、invalid_email。表单校验失败建议 HTTP 422 并返回字段级 errors;限流返回 429 时附 Retry-After 与 limit、remaining、reset_at 等限额信息。

使用方式:按工作流程列出端点清单,对每个端点列举失败场景,逐项选择 HTTP 状态码、设计业务错误码、编写用户可见消息与调用方处理建议、标注可重试性,输出错误码表,并在 OpenAPI 中定义错误响应 Schema。可配套 templates/error-code-template.md 模板;与 endpoint-design、request-response、auth-permission、idempotency-retry、openapi-mock 等技能协作。质量自检覆盖状态码正确性、命名规范、触发条件、用户提示、处理建议、可重试标注、字段级校验、Retry-After、信息不泄露、trace_id 必备等。

适用场景:API 错误响应结构设计、错误码体系建立、给调用方的错误处理指南、调试和可观测性建设。限制:具体实现语言、框架与部署细节暂未提供。