> ## 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 | リソースが見つかりません（メッセージ、チャット、スケジュール…） | 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/ja/advanced/rate-limiting.md)を参照してください。 |
| `INTERNAL_SERVER_ERROR` | 500 | 回復パニックを含む予期しない失敗。 | バックオフで再試行します; ログを確認します。 |
| `QR_CHANNEL_ERROR` | 500 | QRコードを取得できませんでした。 | ログインを再試行します。 |
| `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秒を超えました。 | アクションはまだ完了する可能性があります; 再試行する前にチェックします。 |

Basic Auth に失敗すると、GOWA のハンドラーに到達する前に認証層から `401` が返されます。GOWA の `code` を伴わない `401` は、認証情報の誤りとして扱ってください。

## 安全に再試行中

送信は **等価ではありません**: GOWA には idempotence キーがありません。送信時間 (`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/ja/api-reference/errors.md)
- [メディア処理](https://gowa-docs.mintlify.site/ja/examples/media-handling.md)
- [メッセージを送信中](https://gowa-docs.mintlify.site/ja/examples/sending-messages.md)
- [Chatwoot統合](https://gowa-docs.mintlify.site/ja/integrations/chatwoot.md)
- [デバイスを再接続](https://gowa-docs.mintlify.site/ja/api-reference/device/デバイスを再接続.md)


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