このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。
エラーハンドリング
Flex Forward APIは標準的なHTTPステータスコードと構造化されたエラーレスポンスを使用します。このページでは、エラー形式、ステータスコードの意味、障害処理のガイダンスについて説明します。エラーレスポンス形式
APIは障害の種類に応じて2つのエラーレスポンス形式を返します。 API は障害の種類に応じて3つのエラーレスポンス形式を返します。どの形式が返されるかを理解することで、正確なエラー解析ロジックを記述できます。標準エラー
認証エラー、リソース未検出エラー、サーバーエラーの場合に返されます：バリデーションエラー
リクエストのバリデーション失敗（HTTP 400）の場合に返されます。フィールドレベルのエラー情報を含むdetails 配列が含まれます：
details の各エントリには以下が含まれます：
HTTPステータスコード
バリデーションエラー（400）
バリデーションエラーは、リクエストボディがAPIスキーマの要件を満たしていないことを示します。レスポンスには必ず特定のフィールドパスを含むdetails 配列が含まれます。
一般的な原因：
- 必須フィールドの欠落（
shipment.shipTo、courier、idempotencyKey） - フィールド形式の不正（国コード、メール、電話番号）
- 数値の不正（重量は0より大きい必要があります）
リトライする前に
details 配列にリストされているすべてのバリデーションエラーを修正してください。ラベルが作成されていないため、400レスポンス後も同じ idempotencyKey を再利用できます。認証エラー（401 / 403）
401 Unauthorized
x-rr-apikey または x-rr-apitoken ヘッダーが欠落または無効の場合：
403 Forbidden
認証情報は有効ですが、リクエストされたリソースへのアクセス権がない場合。別のアカウントに属するラベルや追跡情報を取得しようとした場合に発生します：配送業者の下流エラー（502）
配送業者サービスがエラーを返した場合、APIはHTTP 502で応答します。ラベルはデータベースにstatus: failed で保存され、配送業者のエラー詳細が含まれます：
error オブジェクトには以下が含まれます：
リトライ可能なエラーと不可能なエラー
推奨されるリトライ戦略については冪等性とリトライをご覧ください。
トラブルシューティング
Content-Typeヘッダーの欠落
Content-Typeヘッダーの欠落
すべてのPOSTリクエストには
Content-Type: application/json を含める必要があります。これがないとリクエストボディが解析されず、APIは400エラーを返します。ベースURLの誤りまたはHTTPの使用
ベースURLの誤りまたはHTTPの使用
すべてのリクエストはHTTPSを使用する必要があります。正しい環境URLを使用していることを確認してください：
https://api.flexforward.com（本番）または https://sandbox.flexforward.com（開発）。ラベルIDのUUID形式が無効
ラベルIDのUUID形式が無効
GET /labels/{id} と GET /tracking/{id} の id パラメーターは有効なUUIDである必要があります。トラッキング番号や他の識別子形式を渡すと404エラーが返されます。ラベルが作成されたがステータスがfailed
ラベルが作成されたがステータスがfailed
HTTP 201または200で
status: failed のレスポンスは、ラベルは保存されたが配送業者がリクエストを拒否したことを意味します。配送業者のエラーメッセージについては error オブジェクトを確認してください。一般的な原因：無効な住所、サポートされていない配送先、または配送業者アカウントの設定の問題。