エラーコード
エラーは適切なHTTPステータスと{ ok: false, error: { code, message, field?, meta?, request_id } }を返します。200は使用せず、/v1と埋め込み用の一覧はバックエンドと同期します。
エラーの構造
http
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Request-Id: 018f2b00-0000-7000-8000-0000000000ff
{
"ok": false,
"error": {
"code": "wallet.insufficient_balance",
"message": "Số dư ví không đủ để thực hiện giao dịch.",
"field": null,
"meta": null,
"request_id": "018f2b00-0000-7000-8000-0000000000ff"
}
}0000ではなくdomain.reasonを使う理由
HTTP標準： プロキシ、監視、RESTクライアントが標準HTTPステータスを扱えます。
意味が明確： wallet.insufficient_balanceは表を引かず理解でき、新しいコードの追加も既存処理を壊しません。
旧システムが数値を必要とする場合も、不変のコードを翻訳キーとして使えます。
エラー処理の4つの指針
HTTPステータスを先に判定
ステータスで再試行・警告・遮断を判断し、error.codeで利用者向けメッセージを決めます。ステータスはより安定しています。
未知のコードでも処理を止めない
未知のコードはHTTPステータスに基づいて処理し、コードとrequest_idを記録して代替メッセージを表示します。未処理例外を発生させないでください。
request_idを必ず記録
すべてのレスポンスとエラーにX-Request-Idがあります。問い合わせ時の調査に必要です。
429と503のRetry-Afterを尊重
待機時間を固定せずRetry-Afterを参照します。429にはX-RateLimit-Limit / Remaining / Resetもあります。
コードとHTTPの対応表
ドメイン別の一覧です。各エンドポイントのエラーはAPIリファレンスも参照してください。
91件中91件を表示
認証・キー・制限 partner.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
partner.invalid_key | 401 | APIキーが無効です。 | いいえ：同じ内容では再度失敗 |
partner.invalid_signature | 401 | リクエスト署名が無効です。 | いいえ：同じ内容では再度失敗 |
partner.timestamp_expired | 401 | リクエストの時刻がサーバー時刻から大きくずれています。 | いいえ：同じ内容では再度失敗 |
partner.nonce_reused | 401 | このnonceは使用済みです。 | いいえ：同じ内容では再度失敗 |
partner.ip_not_allowed | 403 | このIPアドレスは許可リストにありません。 | いいえ：同じ内容では再度失敗 |
partner.scope_denied | 403 | このAPIキーにはこのエンドポイントを呼び出す権限がありません。 | いいえ：同じ内容では再度失敗 |
partner.key_suspended | 403 | このAPIキーは一時停止中です。 | いいえ：同じ内容では再度失敗 |
partner.key_revoked | 403 | このAPIキーは失効しています。 | いいえ：同じ内容では再度失敗 |
partner.endpoint_disabled | 503 | このエンドポイントグループは一時的に停止中です。 | はい：同じ内容で再試行 |
partner.rate_limited | 429 | リクエスト上限を超えました。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
partner.package_not_visible | 404 | このキーではこのプランを購入できません。 | いいえ：同じ内容では再度失敗 |
partner.daily_quota_exceeded | 429 | 1日のリクエスト上限を超えました。明日再試行してください。 | はい：同じ内容で再試行 |
partner.wrong_host | 403 | このキーは呼び出し先ホストで使用できません。`tke_test_`は`https://api-testing.tongkhoesim.com`、`tke_live_`は`https://api.tongkhoesim.com`を使用してください。 | いいえ：同じ内容では再度失敗 |
API共通エラー internal.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
internal.validation_failed | 400 | 送信されたデータが無効です。 | いいえ：同じ内容では再度失敗 |
internal.invalid_filter | 400 | 絞り込み条件が無効です。 | いいえ：同じ内容では再度失敗 |
internal.invalid_sort_field | 400 | 並べ替え項目が無効です。 | いいえ：同じ内容では再度失敗 |
internal.unauthenticated | 401 | ログインしていないか、セッションが期限切れです。 | いいえ：同じ内容では再度失敗 |
internal.forbidden | 403 | この操作を行う権限がありません。 | いいえ：同じ内容では再度失敗 |
internal.not_found | 404 | 要求されたリソースが見つかりません。 | いいえ：同じ内容では再度失敗 |
internal.route_not_found | 404 | このパスは存在しません。資料でメソッドとパスを確認してください。 | いいえ：同じ内容では再度失敗 |
internal.method_not_allowed | 405 | このHTTPメソッドはサポートされていません。 | いいえ：同じ内容では再度失敗 |
internal.conflict | 409 | 状態の競合により操作を完了できません。 | いいえ：同じ内容では再度失敗 |
internal.unsupported_media_type | 415 | このコンテンツ形式はサポートされていません。 | いいえ：同じ内容では再度失敗 |
internal.rate_limited | 429 | リクエストが多すぎます。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
internal.server_error | 500 | システムエラーが発生しました。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
internal.service_unavailable | 503 | サービスを一時的に利用できません。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
internal.limit_exceeded | 422 | 上限に達しました。一部の項目を削除してから再試行してください。 | いいえ：同じ内容では再度失敗 |
internal.money_frozen | 503 | 台帳の確認のため金融取引を一時停止しています。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
プラン一覧 catalog.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
catalog.cursor_mismatch | 400 | このカーソルは現在の絞り込み条件と一致しません。cursorパラメーターを外し、最初のページから取得してください。 | いいえ：同じ内容では再度失敗 |
見積もり・注文 order.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
order.quote_not_found | 404 | 見積もりが見つかりません。 | いいえ：同じ内容では再度失敗 |
order.quote_expired | 409 | この見積もりは期限切れです。新しく作成してください。 | いいえ：同じ内容では再度失敗 |
order.quote_already_committed | 409 | この見積もりはすでに注文として確定しています。 | いいえ：同じ内容では再度失敗 |
order.package_not_allowed | 400 | このプランは存在しないか、購入できません。 | いいえ：同じ内容では再度失敗 |
order.not_deliverable | 409 | この注文は未完了のため、この操作は利用できません。 | いいえ：同じ内容では再度失敗 |
order.quantity_limit_exceeded | 400 | eSIMの数が注文ごとの上限を超えています。 | いいえ：同じ内容では再度失敗 |
order.fulfillment_config_changed | 409 | プランの提供設定が変更されました。新しい見積もりを作成してください。 | いいえ：同じ内容では再度失敗 |
order.refund_suggestion_pending | 409 | この注文には承認待ちの返金提案があります。先に対応してください。 | いいえ：同じ内容では再度失敗 |
eSIM esim.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
esim.out_of_stock | 409 | このプランの在庫が不足しています。 | いいえ：同じ内容では再度失敗 |
esim.not_cancellable | 409 | このeSIMは取り消せる状態ではありません。 | いいえ：同じ内容では再度失敗 |
esim.lpa_not_available | 409 | このeSIMにはまだLPAコードがありません（未開通または未登録）。 | いいえ：同じ内容では再度失敗 |
esim.not_eligible | 409 | このeSIMは追加チャージの対象外です。 | いいえ：同じ内容では再度失敗 |
esim.not_activated | 409 | このeSIMは未インストールです。インストールして有効にしてから追加チャージしてください。 | いいえ：同じ内容では再度失敗 |
esim.topup_not_supported | 409 | このプランは追加チャージに対応していません。 | いいえ：同じ内容では再度失敗 |
esim.topup_provider_mismatch | 409 | 追加チャージのプランは別の供給元のものです。このeSIM用に提示されたプランを選択してください。 | いいえ：同じ内容では再度失敗 |
esim.refund_not_eligible | 409 | このeSIMは返金申請の対象外です。 | いいえ：同じ内容では再度失敗 |
esim.refund_request_pending | 409 | このeSIMには保留中の返金申請があります。 | いいえ：同じ内容では再度失敗 |
esim.suspended | 409 | このeSIMは一時停止中です。再開してから操作してください。 | いいえ：同じ内容では再度失敗 |
ウォレット wallet.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
wallet.frozen | 409 | このウォレットは凍結されており、支払いできません。 | いいえ：同じ内容では再度失敗 |
wallet.velocity_hold | 409 | このウォレットは確認のため保留中です。サポートにお問い合わせください。 | いいえ：同じ内容では再度失敗 |
wallet.insufficient_balance | 402 | この取引を完了するにはウォレット残高が不足しています。 | いいえ：同じ内容では再度失敗 |
wallet.deleted | 409 | 送金先ウォレットは削除されているため無効です。 | いいえ：同じ内容では再度失敗 |
wallet.velocity_exceeded | 429 | 短時間の取引が上限を超えたため、ウォレットを確認のため保留しました。 | いいえ：同じ内容では再度失敗 |
返金申請 refund.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
refund.note_required | 400 | 返金を却下する理由を入力してください。 | いいえ：同じ内容では再度失敗 |
販売価格 pricing.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
pricing.no_price_for_buyer | 409 | このプランの販売価格がまだ設定されていません。 | いいえ：同じ内容では再度失敗 |
eSIM供給元 provider.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
provider.disabled | 409 | このプランの供給元が無効のため、販売できません。 | いいえ：同じ内容では再度失敗 |
provider.api_group_disabled | 409 | この供給元のサービスグループは無効です。 | いいえ：同じ内容では再度失敗 |
provider.not_registered | 500 | この供給元の接続設定がありません。 | はい：同じ内容で再試行 |
provider.unsupported | 400 | この供給元はこの操作に対応していません。 | いいえ：同じ内容では再度失敗 |
provider.timeout | 504 | 供給元の応答がタイムアウトしました。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
provider.auth_failed | 502 | 供給元での認証に失敗しました。 | はい：同じ内容で再試行 |
provider.rate_limited | 429 | 供給元がリクエストを制限しています。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
provider.malformed_response | 502 | 供給元から無効なデータが返されました。 | はい：同じ内容で再試行 |
provider.call_failed | 502 | 供給元への呼び出しに失敗しました。 | はい：同じ内容で再試行 |
provider.out_of_stock | 409 | このプランは供給元で在庫切れです。 | いいえ：同じ内容では再度失敗 |
provider.msisdn_taken | 409 | このMSISDNは供給元ですでに別の契約者に割り当てられています。 | いいえ：同じ内容では再度失敗 |
provider.msisdn_exhausted | 409 | 供給元に利用可能なMSISDNがありません。 | いいえ：同じ内容では再度失敗 |
Idempotency idempotency.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
idempotency.conflict | 409 | このIdempotency-Keyは異なる内容ですでに使用されています。 | いいえ：同じ内容では再度失敗 |
供給元の機能 capability.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
capability.not_supported | 422 | このプランは要求された機能に対応していません。 | いいえ：同じ内容では再度失敗 |
テスト・シミュレーション testmode.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
testmode.live_key_forbidden | 403 | このエンドポイントはapi-testing上でテストキー（`tke_test_`）を使用する場合のみ利用できます。同じ組織のテストキーに切り替えてください。 | いいえ：同じ内容では再度失敗 |
testmode.not_test_item | 422 | このeSIMは本番データです。テストモードでは操作できません。実際の注文を取り消すには返金審査を申請してください。 | いいえ：同じ内容では再度失敗 |
testmode.invalid_scenario | 422 | 無効なシナリオです。`data_used_mb`、`status`、`expire_now`、`throttled`のいずれかを指定してください。`status`はreleased|installed|enabled|disabledのみ有効です。 | いいえ：同じ内容では再度失敗 |
testmode.no_sellable_package | 422 | サンプルデータを作成するには、価格が設定された販売可能プランが最低1つ必要です。 | いいえ：同じ内容では再度失敗 |
Webhook webhook.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
webhook.health_check_failed | 422 | ヘルスチェックでWebhook URLから有効な応答がありませんでした。 | いいえ：同じ内容では再度失敗 |
webhook.url_not_allowed | 422 | このWebhook URLは使用できません。公開されたhttps URLが必要です。 | いいえ：同じ内容では再度失敗 |
webhook.not_configured | 404 | このAPIキーにはWebhookが設定されていません。 | いいえ：同じ内容では再度失敗 |
webhook.delivery_not_found | 404 | Webhook配信が見つかりません。 | いいえ：同じ内容では再度失敗 |
webhook.already_configured | 409 | このAPIキーにはWebhookがすでにあります（キーごとに1件）。`PUT /v1/webhooks/{id}`で更新するか、`DELETE /v1/webhooks/{id}`で削除してから作成してください。 | いいえ：同じ内容では再度失敗 |
webhook.not_found | 404 | 呼び出し元APIキーにこのWebhookエンドポイントはありません。 | いいえ：同じ内容では再度失敗 |
組織の状態 org.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
org.invoice_profile_incomplete | 422 | 組織の請求情報が不足しています（法人名、税番号、住所）。 | いいえ：同じ内容では再度失敗 |
org.suspended | 403 | この組織は現在利用停止中です。 | いいえ：同じ内容では再度失敗 |
org.closed | 403 | この組織は閉鎖されています。 | いいえ：同じ内容では再度失敗 |
公開埋め込み embed.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
embed.invalid_token | 401 | 埋め込みトークンが無効です。 | いいえ：同じ内容では再度失敗 |
embed.token_revoked | 410 | この埋め込みチャネルは無効になっています。 | いいえ：同じ内容では再度失敗 |
embed.rate_limited | 429 | 埋め込みチャネルの呼び出しが速すぎます。しばらくしてから再試行してください。 | はい：同じ内容で再試行 |
embed.package_not_visible | 404 | プランが見つかりません。 | いいえ：同じ内容では再度失敗 |
VAT請求書 invoice.*
| code | HTTP | 意味 | 再試行可能？ |
|---|---|---|---|
invoice.order_not_settled | 409 | 返金処理中のため注文の精算が完了していません。数分後に請求書の発行を再試行してください。 | はい：同じ内容で再試行 |
invoice.profile_incomplete | 422 | 組織の請求情報が不足しています。請求書を発行する前に必要事項を入力してください。 | いいえ：同じ内容では再度失敗 |
invoice.already_requested | 409 | この注文にはすでに請求書があります。 | いいえ：同じ内容では再度失敗 |
invoice.nothing_to_invoice | 409 | 返金額を差し引くと請求できる金額はありません。 | いいえ：同じ内容では再度失敗 |
invoice.amount_changed | 409 | 新しい返金により注文金額が変わりました。金額を確認してから請求書を再発行してください。 | はい：同じ内容で再試行 |
invoice.buyer_invalid | 422 | 請求先企業の情報が不足しているか、税番号の形式が無効です。 | いいえ：同じ内容では再度失敗 |