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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.