> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt
> Use this file to discover all available pages before exploring further.
# エラーコード
> Return Helper API が返す可能性のあるすべてのエラーコードと、その意味、ワイヤレベルの HTTP ステータス、レスポンスボディの形、各エラーの取り扱い方。
このページはAIによって自動翻訳されています。不明点や相違がある場合は、[英語版](/reference/error-codes)を正式版として参照してください。
すべての API レスポンスは標準のエンベロープ（`correlationId` + `meta` + payload — [エラーハンドリング](/ja/introduction#error-handling) を参照）を使用します。エラーが発生した場合、`meta.errorCode` が機械可読のエラーキーになります。本ページでは User API と Public API が返却し得るすべての値を列挙します。
## このページの読み方
**Wire HTTP** 列はレスポンスが実際に届く際の HTTP ステータスです。
**`meta.status`** 列はボディ内のアプリケーションレベルのステータスです。
**`meta.errorCode`** 列はクライアントコードで分岐に使用する値です。
**`meta.error`** 列は各エラーの詳細の形を表します。
本 API のほとんどのエラー経路は HTTP `200` を返し、論理的なステータスを `meta.status` に載せます（ソフトエラーの慣習）。少数のケースでは実際の HTTP `400`/`401`/`403`/`409` を返します — これらは API 自身のレスポンスエンベロープが適用される前に発生するか、本来の HTTP の意味を表しているためです。
## バリデーション失敗
ほぼすべての書き込みエンドポイントは FluentValidation を通過します。ここで捕捉されたもの — 必須フィールドの欠落、値の範囲外、無効な国コード、バッチサイズ超過、`Custom(...)` チェックで表現された業務ルール違反など — はすべて 1 つのエラーコードに集約されます：
| Wire HTTP | `meta.status` | `meta.errorCode` | `meta.error` |
| --------- | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | `400` | `VALIDATION_FAILED` | リクエストプロパティ名をキーとし、カンマ区切りのエラーメッセージリストを値に持つオブジェクト。バッチ系エンドポイント（例：`/api/Recall/createRecallByReturnInventoryId`）では `jobEntryList` 内の各項目が個別に提示されるため、どのリスト要素が失敗したかを特定できます。 |
サンプルレスポンスボディ：
```json theme={null}
{
"correlationId": "0HNLB2U6T1QG1:00000001",
"meta": {
"status": 400,
"data": {},
"errorCode": "VALIDATION_FAILED",
"error": {
"returnInventoryId": "'return Inventory Id' must not be empty."
}
}
}
```
`meta.error` を確認してください — キーがどのフィールドが誤っているかを示します。
## 業務ルール・リソースエラー
リクエストは構造的に有効でも、データの現在の状態、アカウント、あるいはサポートインフラストラクチャと矛盾する場合に、業務ロジックから送出されます。各エラーは異なる `errorCode` を持つため、分岐処理が可能です。
| `meta.errorCode` | Wire HTTP | `meta.status` | 発生条件 |
| ---------------------------------------- | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TRACKING_ALREADY_EXIST` | `200` | `400` | 送信した `trackingNumber` がすでに別のアクティブなレコードで使用されています。最も多いのは [Create FBA shipment](/ja/api-reference/fbashipment/create-fba-shipment) で同じ Amazon 追跡番号を二重送信した場合。tracking 値を直接渡す return shipment / resend 作成でも発生し得ます。`meta.error` には衝突したレコードの識別情報が含まれます。 |
| `ACCOUNT_IS_BLOCKED` | `200` | `403` | お客様の API アカウントがブロックされています（例：未払い残高、規約違反）。Return Helper サポートがブロックを解除するまで、すべての書き込みエンドポイントは失敗します。`meta.error.message` に人間可読の理由が含まれます。`support@returnhelper.com` までご連絡ください。 |
| `S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ` | `200` | `404` | S3 からファイルを取得する必要があるエンドポイント（通常は VAS の添付ファイルやラベル成果物）が対象オブジェクトを読み取れませんでした。以前アップロードしたファイルが今も存在しアクセス可能であることをご確認ください。 |
| `UPLOAD_FILE_TO_S3_FAIL` | `200` | `500` | ファイルを S3 にアップロードする必要があるエンドポイントが失敗しました。一過性のインフラ問題です — 同じ冪等キーでリトライしてください。 |
| `REQUEST_CUSTOM_DOMAIN_FAIL` | `200` | `500` | カスタムドメインサービスを呼び出すラベル / ブランディング系エンドポイントが失敗しました。一過性です — リトライしてください。 |
## 認証・アクセス制御失敗
これらはソフトエラーではありません。通常のリクエストパイプラインの前（または外）で生成されるため、実際の HTTP ステータスコードで届きます。
| Wire HTTP | `meta.status` | `meta.errorCode` | 発生条件 |
| --------- | ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `401` | `401` | `null` | `x-rr-apikey` または `x-rr-apitoken` が欠落、形式不正、もしくはアクティブなアカウントに一致しません。`meta.error.message` は `"Missing request header"` のような内容になります。 |
| `403` | `403` | `null` | `RrForbiddenException` が送出された場合 — お客様のアカウントは認証されていますが、当該操作の権限がありません（例：他テナントのレコードを読もうとした）。`meta.error.message` は人間可読です。 |
## 競合・未検出
頻度は低いですが発生し得ます：
| Wire HTTP | `meta.status` | `meta.errorCode` | 発生条件 |
| --------- | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` | `404` | `null` | `RrInvalidException` または `RrNotfoundException` が送出された場合 — 参照したリソース（ID 指定）が存在しないか、お客様のアカウントに属していません。`meta.error.message` は人間可読です。 |
| `409` | `409` | `null` | `DuplicateTransactionException` が送出された場合 — 送信した状態変更リクエストが、冪等性レイヤーによって進行中または完了済みのリクエストの重複と認識されました。`meta.error` には `transactionType`、`headId`、`uniqueChargeKey`、`message` が含まれます。no-op として扱ってください — 元のリクエストは成功しています。 |
冪等性キーの失敗
以下は、書き込み系エンドポイントで `x-returnhelper-idempotency-key` ヘッダーを送信した場合に適用され、実際の HTTP ステータスコードで返ります。
| Wire HTTP | `meta.status` | `meta.errorCode` | 発生条件 |
| --------- | ------------- | --------------------------------- | ----------------------------------------------------------------- |
| `400` | `400` | `IDEMPOTENCY_KEY_INVALID` | キーが「1〜128 文字、英数字と `_`、`.`、`:`、`-` のみ」の条件を満たしていない場合。 |
| `409` | `409` | `IDEMPOTENCY_REQUEST_IN_PROGRESS` | 同じキーのリクエストがまだ実行中の場合。完了後に再試行してください。 |
| `409` | `409` | `IDEMPOTENCY_KEY_ALREADY_USED` | 同じキーのリクエストが検証ウィンドウ内で既に完了している場合。no-op として扱ってください — 元のリクエストは処理済みです。 |
キーのスコープは 1 つのアカウントと 1 つの HTTP メソッド・ルートの組み合わせです。そのため、同じキーの値を別のエンドポイントで使っても衝突しません。
## クライアント側の推奨処理
擬似コード：
```
response = call(endpoint, body)
if response.status == 401:
reauth or alert ops
elif response.status == 403:
surface meta.error.message — account or permission issue
elif response.status == 409:
treat as success (idempotency replay) — do NOT retry
elif response.status == 200:
meta = response.body.meta
if meta.errorCode == 'VALIDATION_FAILED':
surface meta.error map to the user — field-level messages
elif meta.errorCode == 'TRACKING_ALREADY_EXIST':
handle duplicate — likely already created on a previous attempt
elif meta.errorCode == 'ACCOUNT_IS_BLOCKED':
halt all calls, alert ops, do not retry
elif meta.errorCode in ('UPLOAD_FILE_TO_S3_FAIL', 'REQUEST_CUSTOM_DOMAIN_FAIL'):
retry with the same idempotency key (transient infra)
elif meta.errorCode == 'S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ':
re-upload the source file, then retry
elif meta.status == 200 and meta.errorCode is null:
success — read the payload at the top level
elif meta.status == 404 and meta.errorCode is null:
resource not found — the ID is wrong or out of scope
```
`correlationId` はすべてのレスポンスに含まれます。**必ずログに記録してください** — Return Helper のサポートが内部システムで特定のリクエストを追跡する手がかりになります。
## 各エラーコードの定義場所
本ページに掲載しているエラーコードは `ReturnRequestApiModel.RrException` 名前空間の `RrErrorCode` 定数に由来します。本ページに記載のない `errorCode` 値に遭遇した場合は、未文書化の内部エラーとして扱い、`correlationId` とともにサポートへご報告ください。