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

# エラーハンドリング

> HTTPステータスコード、エラーレスポンス形式、トラブルシューティングガイド

<Note>
  このページは英語から翻訳されています。[英語版](/introduction)が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。
</Note>

# エラーハンドリング

Flex Forward APIは標準的なHTTPステータスコードと構造化されたエラーレスポンスを使用します。このページでは、エラー形式、ステータスコードの意味、障害処理のガイダンスについて説明します。

## エラーレスポンス形式

APIは障害の種類に応じて2つのエラーレスポンス形式を返します。

API は障害の種類に応じて3つのエラーレスポンス形式を返します。どの形式が返されるかを理解することで、正確なエラー解析ロジックを記述できます。

| 形式         | 発生条件                   | ステータスコード                             |
| ---------- | ---------------------- | ------------------------------------ |
| 標準エラー      | 認証、リソース未検出、サーバーエラー     | 401, 403, 404, 405, 500              |
| バリデーションエラー | リクエストボディのスキーマバリデーション失敗 | 400                                  |
| ラベル失敗      | 配送業者がラベルリクエストを拒否       | 502（`status: failed` での 201/200 も含む） |

### 標準エラー

認証エラー、リソース未検出エラー、サーバーエラーの場合に返されます：

```json theme={null}
{
  "error": "Unauthorized"
}
```

### バリデーションエラー

リクエストのバリデーション失敗（HTTP 400）の場合に返されます。フィールドレベルのエラー情報を含む `details` 配列が含まれます：

```json theme={null}
{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.shipTo.address.countryCode",
      "message": "must be a valid ISO 3166-1 alpha-2 country code"
    },
    {
      "field": "shipment.parcels[0].weight",
      "message": "must be greater than 0"
    }
  ]
}
```

`details` の各エントリには以下が含まれます：

| フィールド     | 説明                                    |
| --------- | ------------------------------------- |
| `field`   | 無効なフィールドへのドット区切りのパス（配列インデックスはブラケット表記） |
| `message` | バリデーション失敗の内容を示す人間が読める説明               |

## HTTPステータスコード

| ステータス | 意味          | 発生条件                                         | リトライ可能                           |
| ----- | ----------- | -------------------------------------------- | -------------------------------- |
| 200   | OK / 冪等リプレイ | GETリクエスト成功、または以前使用した `idempotencyKey` でのPOST | 該当なし                             |
| 201   | 作成完了        | ラベルが正常に作成された                                 | 該当なし                             |
| 400   | リクエスト不正     | リクエストボディのバリデーション失敗                           | 不可 — リクエストを修正                    |
| 401   | 認証エラー       | Bearerトークンが不足または無効                           | 不可 — Flex Forwardチームから有効なトークンを取得 |
| 403   | アクセス禁止      | トークンは有効だが、リクエストされたリソースへのアクセス権がない             | 不可 — アカウント権限を確認                  |
| 404   | 未検出         | ラベルIDまたはシッピングアカウントが存在しない                     | 不可 — IDを確認                       |
| 405   | メソッド不許可     | このエンドポイントでサポートされていないHTTPメソッド                 | 不可 — メソッドを確認                     |
| 500   | 内部サーバーエラー   | 予期しないサーバー障害                                  | 可能 — バックオフでリトライ                  |
| 502   | バッドゲートウェイ   | 配送業者サービスがエラーを返した                             | 可能 — バックオフでリトライ                  |

## バリデーションエラー（400）

バリデーションエラーは、リクエストボディがAPIスキーマの要件を満たしていないことを示します。レスポンスには必ず特定のフィールドパスを含む `details` 配列が含まれます。

一般的な原因：

* 必須フィールドの欠落（`shipment.shipTo`、`courier`、`idempotencyKey`）
* フィールド形式の不正（国コード、メール、電話番号）
* 数値の不正（重量は0より大きい必要があります）

<Note>
  リトライする前に `details` 配列にリストされているすべてのバリデーションエラーを修正してください。ラベルが作成されていないため、400レスポンス後も同じ `idempotencyKey` を再利用できます。
</Note>

## 認証エラー（401 / 403）

### 401 Unauthorized

Bearerトークンが欠落、不正な形式、または期限切れの場合：

```json theme={null}
{
  "error": "Unauthorized"
}
```

`Authorization` ヘッダーが存在し、正しい形式であることを確認してください：`Bearer YOUR_API_TOKEN`

### 403 Forbidden

トークンは有効ですが、リクエストされたリソースへのアクセス権がない場合。別のアカウントに属するラベルや追跡情報を取得しようとした場合に発生します：

```json theme={null}
{
  "error": "Forbidden"
}
```

## 配送業者の下流エラー（502）

配送業者サービスがエラーを返した場合、APIはHTTP 502で応答します。ラベルはデータベースに `status: failed` で保存され、配送業者のエラー詳細が含まれます：

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}
```

`error` オブジェクトには以下が含まれます：

| フィールド     | 説明                 |
| --------- | ------------------ |
| `code`    | 機械可読なエラーコード        |
| `message` | 配送業者からの人間が読めるエラー説明 |

<Warning>
  502レスポンスは、ラベルリクエストが配送業者に到達し、拒否されたことを意味します。リトライする前にエラーメッセージを確認してください — 一部の配送業者エラー（住所バリデーションなど）は一時的なものではなく、リクエストの変更が必要です。
</Warning>

## リトライ可能なエラーと不可能なエラー

| エラータイプ      | リトライ可能 | アクション                                     |
| ----------- | ------ | ----------------------------------------- |
| 400 バリデーション | 不可     | `details` に基づいてリクエストボディを修正                |
| 401 認証エラー   | 不可     | Flex Forwardチームから有効なトークンを取得               |
| 403 アクセス禁止  | 不可     | リソースへのアカウントアクセスを確認                        |
| 404 未検出     | 不可     | ラベルIDまたはシッピングアカウントを確認                     |
| 500 サーバーエラー | 可能     | 同じ `idempotencyKey` でバックオフを使用してリトライ       |
| 502 配送業者エラー | 場合による  | エラーメッセージを確認 — 一時的な問題はリトライ可能、バリデーションの問題は不可 |

推奨されるリトライ戦略については[冪等性とリトライ](/ja/idempotency-and-retries)をご覧ください。

## トラブルシューティング

<AccordionGroup>
  <Accordion title="Content-Typeヘッダーの欠落">
    すべてのPOSTリクエストには `Content-Type: application/json` を含める必要があります。これがないとリクエストボディが解析されず、APIは400エラーを返します。
  </Accordion>

  <Accordion title="ベースURLの誤りまたはHTTPの使用">
    すべてのリクエストはHTTPSを使用する必要があります。正しい環境URLを使用していることを確認してください：`https://api.flexforward.com`（本番）または `https://sandbox.flexforward.com`（開発）。
  </Accordion>

  <Accordion title="ラベルIDのUUID形式が無効">
    `GET /labels/{id}` と `GET /tracking/{id}` の `id` パラメーターは有効なUUIDである必要があります。トラッキング番号や他の識別子形式を渡すと404エラーが返されます。
  </Accordion>

  <Accordion title="ラベルが作成されたがステータスがfailed">
    HTTP 201または200で `status: failed` のレスポンスは、ラベルは保存されたが配送業者がリクエストを拒否したことを意味します。配送業者のエラーメッセージについては `error` オブジェクトを確認してください。一般的な原因：無効な住所、サポートされていない配送先、または配送業者アカウントの設定の問題。
  </Accordion>
</AccordionGroup>