メインコンテンツへスキップ

​
エラーハンドリング

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

​
エラーレスポンス形式

APIは障害の種類に応じて2つのエラーレスポンス形式を返します。 API は障害の種類に応じて3つのエラーレスポンス形式を返します。どの形式が返されるかを理解することで、正確なエラー解析ロジックを記述できます。
形式発生条件ステータスコード
標準エラー認証、リソース未検出、サーバーエラー401, 403, 404, 405, 500
バリデーションエラーリクエストボディのスキーマバリデーション失敗400
ラベル失敗配送業者がラベルリクエストを拒否502（status: failed での 201/200 も含む）

​
標準エラー

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

​
バリデーションエラー

リクエストのバリデーション失敗（HTTP 400）の場合に返されます。フィールドレベルのエラー情報を含む details 配列が含まれます： 
{
  "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ステータスコード

ステータス意味発生条件リトライ可能
200OK / 冪等リプレイ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より大きい必要があります）
リトライする前に details 配列にリストされているすべてのバリデーションエラーを修正してください。ラベルが作成されていないため、400レスポンス後も同じ idempotencyKey を再利用できます。

​
認証エラー（401 / 403）

​
401 Unauthorized

Bearerトークンが欠落、不正な形式、または期限切れの場合： 
{
  "error": "Unauthorized"
}
Authorization ヘッダーが存在し、正しい形式であることを確認してください：Bearer YOUR_API_TOKEN

​
403 Forbidden

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

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

配送業者サービスがエラーを返した場合、APIはHTTP 502で応答します。ラベルはデータベースに status: failed で保存され、配送業者のエラー詳細が含まれます： 
{
  "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配送業者からの人間が読めるエラー説明
502レスポンスは、ラベルリクエストが配送業者に到達し、拒否されたことを意味します。リトライする前にエラーメッセージを確認してください — 一部の配送業者エラー（住所バリデーションなど）は一時的なものではなく、リクエストの変更が必要です。

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

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

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

すべてのPOSTリクエストには Content-Type: application/json を含める必要があります。これがないとリクエストボディが解析されず、APIは400エラーを返します。
すべてのリクエストはHTTPSを使用する必要があります。正しい環境URLを使用していることを確認してください：https://api.flexforward.com（本番）または https://sandbox.flexforward.com（開発）。
GET /labels/{id} と GET /tracking/{id} の id パラメーターは有効なUUIDである必要があります。トラッキング番号や他の識別子形式を渡すと404エラーが返されます。
HTTP 201または200で status: failed のレスポンスは、ラベルは保存されたが配送業者がリクエストを拒否したことを意味します。配送業者のエラーメッセージについては error オブジェクトを確認してください。一般的な原因：無効な住所、サポートされていない配送先、または配送業者アカウントの設定の問題。