接口约定与鉴权

调用公开 API 前，先确认对应端点的鉴权方式和响应结构。

成功响应按端点解析：目录、查询、/me 和同步状态使用 data；发布、whoami、删除使用 result；标题匹配直接返回 version、decision、candidates。番剧预览使用顶层 previewUrl，不能按普通发布回执读取。

应用 JSON 错误包含 ok: false 和 error.code、error.message、error.requestId；reason、retryable、retryAfterMs、details 为可选字段。缺少 retryable 不表示可以重试。公开 RSS 的错误通常是纯文本；Torznab 协议错误是 XML，HTTP 状态仍可能为 200；边缘拦截还可能返回 HTML。先检查 HTTP 状态与 Content-Type，再解析正文。

发布前用 GET 同一路径核验 groupSlug 和 scopes。发布成功回执只保证 releaseId、revision，可能含 torrentObjectId，不包含字幕组身份或 fileSize。资源 ID 使用端点要求的 rel_* 或 orel_*；字幕组通常用 slug，但其他类 RSS 的 groupId 使用组织 ID。

发布重试与删除后重新发布

普通发布的同一次请求建议使用 Idempotency-Key。同一 API Key、同一发布端点重试相同内容时，保留原值；该值去除首尾空白后须为 1–256 字符。未提供、空值或超过上限时会按新命令处理，不能依赖命令回放。跨站浏览器预检目前不允许该请求头；需要此保证的客户端应从服务端调用。

成功命令的重试返回原 releaseId 与 revision，不会重新发布。即使原资源已经删除，同一个命令仍返回旧回执，不会恢复资源；删除后有意使用同一种子重新发布，应使用新的 Idempotency-Key。

从首次受理开始，Idempotency-Key 绑定完整请求。切换发布与预览，或更改资源内容、Nyaa 选项、显式发布时间、上传文件时，应使用新键。上传完成或已有回执不能绕过已保存的绑定；同键改参返回 409 CONFLICT。

升级前已上传但尚未完成的请求，若缺少完整绑定，会返回 409 CONFLICT，error.reason 为 legacy_request_binding_missing。此时请使用新键重新提交完整请求。已完成的旧请求仍按原回执重放。

收到 429 RATE_LIMIT_EXCEEDED 时，按 Retry-After 的秒数等待。发布暂时繁忙、限流服务不可用或上传结果待确认时可返回 503 SERVICE_UNAVAILABLE。503 带 Retry-After 时按它等待，再用原 key 重试同一请求；没有该头时先核查现有发布并保留 error.requestId。失败或连接中断不证明未写入，不要立即批量重试，也不要为一次不确定的结果反复换新 key。