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

# 错误处理

> GOWA 的响应信封、错误代码和HTTP状态，以及如何处理它们。

## 响应信封

每个JSON响应都有相同的形状：

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": { }
}
```

| 字段 | 描述 |
| - | - |
| `code` | `SUCCESS` 或一个错误代码。请使用这个以及HTTP状态来分支。 |
| `message` | 可读的细节。单词可以在发布之间改变；不解析它。 |
| `results` | 成功时传输负载。错误时通常省略。 |

## 错误代码

| 代码 | HTTP | 含义 | 做什么 |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | 缺少或无效字段。`message` 给它命名。 | 修复请求。 |
| `INVALID_JID` | 400 | 此号码不在WhatsApp上，或者JID格式不正确。 | 请检查号码；不要重试。 |
| `ALREADY_LOGGED_IN` | 400 | 已登录的设备登录请求。 | 没有东西，或先登出。 |
| `DEVICE_ID_REQUIRED` | 400 | 没有给定设备，服务器有零或几个设备。 | 发送 `X-Device-Id` 。 |
| `AUTHENTICATION_ERROR` | 401 | 设备未登录到 WhatsApp (或WhatsApp 身份验证失败)。 | 检查 `/devices/{id}/status`；必要时重新配对。 |
| `NOT_FOUND` | 404 | 找不到资源 (消息、聊天、schedule…)。 | 检查 ID。 |
| `DEVICE_NOT_FOUND` | 404 | `X-Device-Id`命名一个未知设备。 | 检查栏位 ID 或 JID。 |
| `AVATAR_HIDDEN` | 403 | 个人资料图片被隐私设置隐藏。 | 不要将此视为已确认的缺失，或仅在此结果上擦除缓存的图片。 |
| `AVATAR_NOT_SET` | 404 | 联系人没有个人资料图片。 | 只在检查此代码后才清除缓存的图片，而不是任意404。 |
| `CROSS_SITE_REQUEST_BLOCKED` | 403 | 浏览器来源不可信。 | 通过 HTTP(S) 提供仪表盘服务并配置确切的信任来源。 |
| `CONTEXT_ERROR` | 408 | 该操作已在内部被取消或超时。 | 重试一次。 |
| `WA_REACHOUT_TIMELOCK` | 429 | WhatsApp 暂时阻止该帐户中的新聊天。 | 停止外联；参见[发送限制](https://gowa-docs.mintlify.site/zh/advanced/rate-limiting.md)。 |
| `INTERNAL_SERVER_ERROR` | 500 | 意外失败，包括找回的恐慌。 | 重试备份；检查日志。 |
| `QR_CHANNEL_ERROR` | 500 | 无法获取二维码。 | 重试登录。 |
| `SESSION_SAVED_ERROR` | 500 | 无法保持会话。 | 检查存储和权限。 |
| `UPLOAD_MEDIA_ERROR` | 500 | 媒体上传到 WhatsApp 失败。 | 重试；检查大小和格式。 |
| `WEBHOOK_ERROR` | 500 | Webhook 配置或发送错误。 | 请检查Webhook URL。 |
| `INVALID_WA_CLI` | 500 | 设备的 WhatsApp 客户端未初始化。 | 重新连接或重新登录。 |
| `DEVICE_MANAGER_UNAVAILABLE` | 503 | 设备管理器未初始化。 | 很快重试；检查启动日志。 |
| `GATEWAY_TIMEOUT` | 504 | 请求超过45秒。 | 操作可能仍然完成；请在重试前检查。 |

在到达GOWA处理程序之前，基本认证失败将从认证层返回`401`；将没有GOWA`code`的任何`401`视为错误凭据。

## 安全重试

发送操作**不具备幂等性**：GOWA 没有幂等键。如果发送超时（`504`、网络错误），消息可能已经送达。重新发送前，请使用 `GET /chat/{chat_jid}/messages?is_from_me=true&limit=5` 检查聊天记录，或接受重复发送的风险。

| 重试 | 不重试 |
| - | - |
| `500 INTERNAL_SERVER_ERROR`, `UPLOAD_MEDIA_ERROR`, `CONTEXT_ERROR`, `503` | `400` 错误，`INVALID_JID`，`404`，`401`，`WA_REACHOUT_TIMELOCK` |

使用指数回退加上上限，并限制尝试。

```javascript theme={null}
async function gowa(path, body, attempt = 1) {
  const res = await fetch(`http://localhost:3000${path}`, {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
      "Content-Type": "application/json",
      "X-Device-Id": "my-device",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (res.ok) return data.results;

  const retryable = [500, 503].includes(res.status) && data.code !== "INVALID_JID";
  if (retryable && attempt < 4) {
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    return gowa(path, body, attempt + 1);
  }
  throw Object.assign(new Error(data.message || res.statusText), { code: data.code, status: res.status });
}
```

## 调试

* 用 `APP_DEBUG=true` 运行详细日志。
* 检查设备：`GET /devices/{device_id}/status`（`is_connected`、`is_logged_in`）。
* `GET /health` 只确认进程和数据库已经运行；它不会检查 WhatsApp 的连接。


## Related topics

- [错误](https://gowa-docs.mintlify.site/zh/api-reference/errors.md)
- [媒体处理](https://gowa-docs.mintlify.site/zh/examples/media-handling.md)
- [Webhooks](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md)
- [WhatsApp 频道](https://gowa-docs.mintlify.site/zh/examples/newsletters.md)
- [提交WebAuthn的密码配对](https://gowa-docs.mintlify.site/zh/api-reference/app/提交webauthn的密码配对.md)


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