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" }。可以把它当存活或就绪探针用。