HTTP 状态码与错误响应

咏唱引擎 API 以 JSON 配合 HTTP 状态码返回错误。每个错误体的结构始终一致，因此你可以统一记录并据此分支处理。

错误结构

{ "error": "message describing what went wrong" }

具体消息因接口而异。切勿解析消息用于逻辑判断；应基于 HTTP 状态码分支。

状态	含义	处理方式
`400 Bad Request`	请求中缺失或格式错误的字段。	修正请求后重试。
`401 Unauthorized`	缺失、过期或无效的会话令牌 / API 密钥。	重新认证或轮换密钥。
`403 Forbidden`	已认证但无权限（例如非管理员调用管理员接口）。	用有权限的账户登录。
`404 Not Found`	资源不存在，或对本账户不可见。	检查 ID、slug 与按站点作用域。
`409 Conflict`	请求与现有状态冲突（例如重复发票）。	获取当前状态并协调。
`429 Too Many Requests`	超出限流。	退避后按指数延迟重试。
`500 Internal Server Error`	意外的服务端错误。	退避后重试。若持续出现请报告。
`503 Service Unavailable`	某依赖（通常是 PostgreSQL）不可用。`/healthz` 在数据库连通性失败时返回此码。	退避后重试。

GET /healthz 在数据库可达时返回 { "status": "ok" }，否则返回 503 { "error": "database unavailable" }。可将其用作存活或就绪探针。