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

エラーハンドリング

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

エラーレスポンス形式

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

形式	発生条件	ステータスコード
標準エラー	未対応の配送業者/商品、認証、リソース未検出、競合、レート制限、サーバーエラー	400, 401, 403, 404, 409, 429, 500。GETエンドポイントでは502も
バリデーションエラー	リクエストボディのスキーマバリデーション失敗	400
ラベル失敗	配送業者がラベルリクエストを拒否。`status: failed` の `LabelResponse`	`POST /labels` での 502、または冪等リプレイで保存済みの失敗結果が返る場合は 200
失敗ラベルの読み取り	配送業者への送信が失敗したラベルの読み取り。`LabelFailedResponse`	`GET /labels/{id}` と `GET /tracking/{id}` での 422

標準エラー

未対応の配送業者/商品、認証エラー、競合、リソース未検出エラー、サーバーエラーなどの障害の場合に返されます。形式は { "error": string, "code"?: string } です：

{
  "error": "Label not found"
}

error のテキストは参考情報であり、予告なく変更される場合があります。HTTPステータスコードと、存在する場合は code で分岐してください — メッセージ本文で分岐しないでください。 code フィールドは一部のエラーレスポンスに設定されます。IDEMPOTENCY_CONFLICT と DUPLICATE_CUSTOMER_ORDER_NUMBER はHTTP 409の競合を区別します。

`code`	意味
`IDEMPOTENCY_CONFLICT`	HTTP 409：キーが異なるリクエスト本文で使用されました。リプレイには元の本文を使用するか、変更したリクエストには新しいキーを使用してください。
`DUPLICATE_CUSTOMER_ORDER_NUMBER`	HTTP 409：注文番号がすでにアカウント内に存在します。そのラベルを取得するか、新しいラベルには別の注文番号を使用してください。
`COURIER_ERROR`	配送業者がラベルリクエストを拒否しました。ラベルレスポンスではHTTP 502で `error.code` に含まれ、失敗ラベルの読み取りでは `errorCode` として返されます。

code は任意で未知の値もあり得ます。コードがない場合はHTTPステータスで処理してください。

バリデーションエラー

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

{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.parcels.0.weight",
      "message": "must be >= 0"
    }
  ]
}

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

フィールド	説明
`field`	無効なフィールドへのドット区切りのパス。配列インデックスはドット区切りの数字で表されます（例：`shipment.parcels.0.weight`）。
`message`	バリデーション失敗の内容を示す人間が読める説明

最初のバリデーションエラーのみが返されます。修正して再送信すると、次のエラーが表示されます。 HTTP 400では標準エラー形状が使われることもあります（例：配送業者や商品が未対応の場合）。読み取る前に details が存在するかを確認してください。すべての400にフィールドレベルのエラーが含まれるとは限りません。

HTTPステータスコード

ステータス	意味	発生条件	リトライ可能
200	OK / 冪等リプレイ	GETリクエスト成功、または同じキーと本文をリプレイする `POST /labels`。保存済み結果は `status: failed` の場合があります	該当なし
201	作成完了	ラベルが正常に作成された	該当なし
400	リクエスト不正	検証失敗または未対応の配送業者/商品	不可 — `details` があれば確認し、なければ `error` と `code` を確認して修正
401	認証エラー	`x-rr-apikey` / `x-rr-apitoken` が不足または無効	不可 — User Portalから有効な認証情報を取得
403	アクセス禁止	認証情報は有効だが、アカウントが許可されていない（例：ブロックされたアカウント）	不可 — アカウント権限を確認
404	未検出	ラベルIDまたはシッピングアカウントが存在しない	不可 — IDを確認
409	競合	本文が異なるキーの再利用、または注文番号の重複	不可 — `code` に従って元の本文/新しいキー、または別の注文番号を使用
422	処理不可能なエンティティ	ラベルは存在するが配送業者への送信が失敗し、文書または追跡情報を利用できない（`GET /labels/{id}`、`GET /tracking/{id}`）	不可 — 新しいラベルを作成してください
429	リクエスト過多	アカウントのリクエストレート上限を超過。適用開始前にクライアントが処理を実装できるよう、すべてのエンドポイントで宣言されています（レート制限を参照）	可能 — `Retry-After` ヘッダーの秒数だけ待ってからリトライ
500	内部サーバーエラー	予期しないサーバー障害	可能 — バックオフでリトライ
502	バッドゲートウェイ	配送業者がラベルリクエストを拒否し、ラベルは `status: failed` で保存される	同じ `idempotencyKey` では不可 — 原因を修正してから新しいリクエストを送信してください（失敗したラベルのリトライを参照）

ラベル作成結果の読み方

POST /labels は 200、201、502 のいずれでも同じ LabelResponse 形式を返します。HTTPステータスコードは、この呼び出しでラベルを作成したのか、以前の試行をリプレイしたのか、配送業者に拒否されたのかを示します。ラベルが存在するかどうかは status フィールドが示します。

POST /labels では、HTTPステータスコードではなく status フィールドで分岐してください。冪等リプレイは最初の試行が配送業者で失敗していてもHTTP 200を返すため、200レスポンスに status: failed が含まれることがあります。

HTTP	`status`	`error`	意味	対応
201	`created`	`null`	この呼び出しで配送業者にラベルが作成された	`id` を保存し、書類取得と追跡に進む
200	`created`	`null`	以前に成功した試行のリプレイ	201と同じ — 新しいラベルは作成されていない
200	`failed`	オブジェクト	配送業者に拒否された以前の試行のリプレイ	同じキーでリトライしない。失敗したラベルのリトライを参照
502	`failed`	オブジェクト	配送業者がこのリクエストを拒否した。試行は `idempotencyKey` に紐付けて保存される	`error.message` を確認し、リクエストを修正して、新しい `idempotencyKey` と `customerOrderNumber` で再送する

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

スキーマバリデーションエラーは、リクエストボディがAPIの要件を満たしていないことを示し、特定のフィールドパスを含む details 配列が含まれます。その他のHTTP 400エラーは、details を含まない標準エラー形状を使用します。一般的な原因：

必須フィールドの欠落（shipment.shipTo、courier、idempotencyKey）
フィールドの型または長さが不正（例：countryCode は正確に2文字である必要があります）
数値が負の値（weight と寸法は負の値であってはなりません）
無効な order.customerOrderNumber（最大40文字、ASCII英字、数字、-、_ のみ使用可能）
未対応の label.format（PDF または PNG を使用）、または商品の unitPrice.currency（USD のみ受け付け）

リトライする前に、報告されたエラーを修正してください。ラベルが作成されていないため、400レスポンス後も同じ idempotencyKey を再利用できます。

認証エラー（401 / 403）

401 Unauthorized

x-rr-apikey または x-rr-apitoken ヘッダーが欠落または無効の場合：

{
  "error": "unauthorized"
}

両方のヘッダーが存在することを確認してください：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

403 Forbidden

認証情報は有効ですが、アカウントがAPIの呼び出しを許可されていない場合です（例：ブロックされたアカウント）：

{
  "error": "Forbidden: account is blocked"
}

別のアカウントに属するラベルまたは追跡レコードは、403ではなく404を返します。

配送業者の下流エラー 502 と 422

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

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}

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

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

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

失敗したラベルに対してその後 GET /labels/{id} または GET /tracking/{id} を呼び出すと、HTTP 422 で LabelFailedResponse ボディが返されます — そのラベルの文書や追跡情報は利用できません：

{
  "error": "Label creation failed",
  "errorCode": "COURIER_ERROR",
  "errorMessage": "Address validation failed at courier"
}

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

エラータイプ	リトライ可能	アクション
400 Bad Request	不可	`details` があれば確認し、なければ `error` と `code` を確認して修正
401 認証エラー	不可	User Portal（Settings → Signing Key and API Token）から有効な認証情報を取得
403 アクセス禁止	不可	リソースへのアカウントアクセスを確認
404 未検出	不可	ラベルIDまたはシッピングアカウントを確認
409 競合	不可	`code` に従って元の本文/新しいキー、または別の注文番号を使用
422 処理不可能なエンティティ	不可	ラベルの配送業者への送信が失敗しました — 新しいラベルを作成してください
429 リクエスト過多	可能	`Retry-After` 秒待ってから、同じ `idempotencyKey` でリトライ
500 サーバーエラー	可能	同じ `idempotencyKey` でバックオフを使用してリトライ
502 配送業者エラー	同じキーでは不可	原因を修正してから、新しい `idempotencyKey` と `customerOrderNumber` で新しいリクエストを送信 — 失敗したラベルのリトライを参照

推奨されるリトライ戦略については冪等性とリトライをご覧ください。

トラブルシューティング

Content-Typeヘッダーの欠落

すべてのPOSTリクエストには Content-Type: application/json を含める必要があります。これがないとリクエストボディが解析されず、APIは400エラーを返します。

ベースURLの誤りまたはHTTPの使用

すべてのリクエストはHTTPSを使用する必要があります。正しい環境URLを使用していることを確認してください：https://api.flexforwardship.com（本番）または https://sandbox.flexforwardship.com（開発）。

識別子が見つかりません

GET /labels/{id} と GET /tracking/{id} の id パラメーターは、ラベルのUUIDまたは customerOrderNumber を受け付けます。それ以外の値、または他のアカウントの識別子を渡すと404エラーが返されます。

ラベルが作成されたがステータスがfailed

status: failed のレスポンスは POST /labels からHTTP 502で（または同じ idempotencyKey でリプレイした場合はHTTP 200で）返され、そのラベルをその後読み取るとHTTP 422が返されます。配送業者のエラーメッセージについては error オブジェクト（読み取り時は LabelFailedResponse ボディ）を確認してください。一般的な原因：無効な住所、サポートされていない配送先、または配送業者アカウントの設定の問題。

はじめに

ガイド

ユースケースガイド

プラットフォーム

エラーハンドリング

エラーハンドリング

エラーレスポンス形式

標準エラー

バリデーションエラー

HTTPステータスコード

ラベル作成結果の読み方

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

認証エラー（401 / 403）

401 Unauthorized

403 Forbidden

配送業者の下流エラー 502 と 422

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

トラブルシューティング

​エラーハンドリング

​エラーレスポンス形式

​標準エラー

​バリデーションエラー

​HTTPステータスコード

​ラベル作成結果の読み方

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

​認証エラー（401 / 403）

​401 Unauthorized

​403 Forbidden

​配送業者の下流エラー 502 と 422

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

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

エラーハンドリング

エラーレスポンス形式

標準エラー

バリデーションエラー

HTTPステータスコード

ラベル作成結果の読み方

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

認証エラー（401 / 403）

401 Unauthorized

403 Forbidden

配送業者の下流エラー 502 と 422

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

トラブルシューティング