エラーコード

失敗時は HTTP ステータスコードと message フィールドを確認してください。

エラーレスポンス形式

業務エラーは常に機械可読な code を返すため、プログラムで分岐できます。パラメータ検証エラーや存在しないルートは Laravel 標準形式 { “message”: ”…”, “errors”: { … } } を返します。送信前に入力値の検証を行ってください。

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

エラー

`code`	HTTP	説明
`unauthorized`	401	APIキーが未指定、無効、または無効化されています。
`account_banned`	403	アカウントは停止中です。サポートにご連絡ください。
`invalid_realtime_request`	400	リアルタイムリクエストの形式が不正です（例：country 未指定時に + 国際プレフィックスのない電話番号）。
`idempotency_key_required`	400	リアルタイムリクエストには Idempotency-Key ヘッダーが必要です。
`invalid_idempotency_key`	422	Idempotency-Key が不正です：英数字と . _ : - のみ、1〜128 文字。
`idempotency_conflict`	409	同じ Idempotency-Key が異なる内容のリクエストに使用されました。
`request_in_progress`	409	同一のリアルタイムリクエストが処理中です。少し待って再試行してください（Retry-After: 1）。
`empty_input`	422	アップロードされたファイルに有効な行がありません。
`product_not_found`	422	指定された製品スラッグが存在しないか無効です。
`product_mode_not_supported`	422	このエンドポイントはこの製品モードを受け付けません（リアルタイム製品を一括処理エンドポイントには送れません）。
`invalid_country`	422	その製品は指定された国に対応していません。
`too_few_numbers`	422	提出数が製品の最小件数に満たません。
`too_many_numbers`	422	提出数がプラットフォームの上限を超えています。
`insufficient_balance`	402	残高が不足しています。チャージ後に再試行してください。
`realtime_disabled`	403	このアカウントではリアルタイム検出が有効になっていません。
`realtime_rate_limited`	429	リアルタイム検出のレート制限を超えました。retry_after に従ってください。
`product_pricing_unavailable`	503	この製品の価格が未設定です。サポートにご連絡ください。
`detection_capacity_unavailable`	503	現在利用可能な検出ルートがありません。後でもう一度お試しください。
`realtime_route_unavailable`	503	現在利用可能なリアルタイムルートがありません。後でもう一度お試しください。
`realtime_fact_cache_unavailable`	503	リアルタイム検出の依存サービスが一時的に利用できません。後でお試しください。
`realtime_rate_limiter_unavailable`	503	レートリミッターが一時的に利用できません。後でお試しください。
`internal_error`	500	サーバー内部エラーです。同じ Idempotency-Key での再試行は安全です。

コードを伴わない失敗

すべての失敗に code があるわけではありません。タスクエンドポイントは4つの状況を HTTP ステータスと message だけで報告します。これらの失敗はビジネスエラーの経路に到達する前に発生するためです:

HTTP	状況	本文
`404`	`task_id` が存在しない、または別のアカウントに属しています	`message` のみ
`404`	`GET /v1/tasks/{token}/download` — 結果ファイルが利用できない、期限切れ、またはダウンロードできない状態です	`message` のみ
`422`	`GET /v1/tasks/{token}/result` — 結果の準備ができていません。タスクが未完了か、ファイルが未生成か、期限切れです	`message` のみ
`422`	リクエストパラメータの検証に失敗しました	`{ "message": …, "errors": { … } }`

これらは HTTP ステータスで分岐してください。message はログとインシデントを読む人向けであり、制御フロー用ではありません。

再試行

失敗への適切な対応は、リクエストを繰り返すことで異なる結果が得られるかどうかによって決まります。

先に対応が必要

変更せずに再試行すると、同じ失敗が繰り返されます。

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

待ってから再試行

一時的な問題です。同じリクエストは後で成功するはずです。

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

結果が不明

リクエストが適用されたかどうかは不明です。同じキーで再試行してください。

internal_error