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

# エラー

> API エラーを適切に処理する

## エラーフォーマット

すべてのエラーレスポンスは一貫した構造に従います。

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Missing required field: name",
      "layer": "product"
    }
  ]
}
```

### errors 配列の読み方

`errors` 配列は根本原因からトップレベルの呼び出し元の順に並んでいます。

* `errors[0]` -- 障害の**根本原因**（デバッグに最も有用）
* `errors[n]` -- エラーを表面化させたトップレベルの呼び出し元

ほとんどの場合、`errors[0].message` を確認するだけで対処可能なエラー説明を取得できます。

***

## HTTP ステータスコード

| コード | 意味              | 説明                     |
| --- | --------------- | ---------------------- |
| 200 | 成功              | リクエストが正常に処理されました       |
| 400 | Bad Request     | 無効なパラメータまたは不正なリクエストボディ |
| 401 | Unauthorized    | 認証情報が欠落しているか無効です       |
| 403 | Forbidden       | 認証情報は有効ですが、権限が不足しています  |
| 404 | Not Found       | リクエストされたリソースが存在しません    |
| 409 | Conflict        | 冪等リクエストが既に処理中です        |
| 429 | Rate Limited    | 短期間にリクエストが多すぎます        |
| 500 | Server Error    | 内部サーバーエラー              |
| 501 | Not Implemented | リクエストされた機能はまだ利用できません   |
| 502 | Bad Gateway     | アップストリームサービスエラー        |

***

## エラーの `layer` フィールド

各エラーには、システムのどの部分がエラーを生成したかを示す `layer` 文字列が含まれます。デバッグ時に根本原因を特定するために、`layer` 値を `message` と合わせて使用してください。

***

## よくあるエラーシナリオ

### 認証エラー (401)

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Token has expired",
      "layer": "user"
    }
  ]
}
```

**解決方法:**

* Merchant ID と秘密鍵が正しいことを確認してください
* SDK が有効な認証情報で初期化されていることを確認してください
* 秘密鍵が登録済みの公開鍵と一致することを確認してください

### バリデーションエラー (400)

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Store name must be between 1 and 100 characters",
      "layer": "store"
    }
  ]
}
```

**解決方法:**

* 必須フィールドが存在することを確認してください
* フィールド値のフォーマットと制約を確認してください
* 金額が表示フォーマット文字列（例：`"29.00"`）であることを確認してください

### 権限エラー (403)

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Only store owner can delete store",
      "layer": "store"
    }
  ]
}
```

**解決方法:**

* API Key が必要な権限を持っていることを確認してください
* ユーザーが正しいストアに所属していることを確認してください

### 冪等性コンフリクト (409)

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Request with this idempotency key is already being processed",
      "layer": "gateway"
    }
  ]
}
```

**解決方法:**

* 元のリクエストの完了を待ってください
* 新しいリクエストには別の `X-Idempotency-Key` を使用してください

***

## コードでのエラー処理

### TypeScript SDK

```typescript theme={"system"}
import { WaffoPancake, WaffoPancakeError } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

try {
  const { store } = await client.stores.create({ name: "My Store" });
} catch (err) {
  if (err instanceof WaffoPancakeError) {
    const rootCause = err.errors[0];
    console.error(`Error [${rootCause.layer}]: ${rootCause.message}`);
    // err.status contains the HTTP status code
  }
}
```

***

## リトライ戦略

以下のステータスコードに対して指数バックオフでリトライしてください。

* **429** -- レート制限（`Retry-After` ヘッダーがある場合はそれに従ってください）
* **500** -- 内部サーバーエラー
* **502** -- Bad Gateway

```javascript theme={"system"}
async function retryRequest(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const status = error.status;
      if (![429, 500, 502].includes(status) || attempt === maxRetries - 1) {
        throw error;
      }
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}
```

<Note>
  `400`、`401`、`403`、`404` エラーはリトライしないでください。これらはリクエスト自体の修正が必要な問題を示しています。
</Note>

***

## 安全なリトライのための冪等性

`X-Idempotency-Key` ヘッダーを使用して、重複を作成せずに書き込み操作を安全にリトライできます。

```bash theme={"system"}
curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Store-Slug: your-store-slug" \
  -H "X-Environment: test" \
  -H "X-Idempotency-Key: order-abc-123" \
  -d '{"productId": "...", "productType": "onetime", "currency": "USD"}'
```

* 冪等キーは **24 時間** キャッシュされます
* 同じキーを送信すると、キャッシュされたレスポンスが返されます
* 元のリクエストがまだ処理中の場合は、`409 Conflict` が返されます