> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP 状态码与错误响应

> 咏唱引擎 API 的错误结构、完整状态码表，以及针对 4xx 与 5xx 响应的重试建议。

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

## 错误结构

```json theme={null}
{ "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` 在数据库连通性失败时返回此码。 | 退避后重试。              |

## 重试建议

* 对 `429`、`500`、`502`、`503`、`504` 使用指数退避叠加抖动重试。
* 不要重试 `400`、`401`、`403`、`404`、`409`，而应修正请求。
* 对于返回 `302` 的长时间下载，重试请求本身（而非预签名 URL）：S3 链接会过期。

## 健康检查

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