request_id と X-Request-Id で UnifyPort API エラーを追跡する

UnifyPort API の障害を調べるには、JSON 応答の request_id または応答ヘッダーの X-Request-Id を保存します。リクエストヘッダーに独自の X-Request-Id を送ると、JSON 応答の client_request_id にその値が返され、アプリケーションログと照合できます。これらは調査用の識別子であり、メッセージ ID、Webhook イベント ID、再送の安全性を保証するキーではありません。

要点

• 業務上の操作、各 HTTP 試行、サーバー側のリクエスト ID を分けて管理します。
• JSON 本文がなくても応答ヘッダーを読みます。削除成功時の 204 も対象です。
• タイムアウトではサーバー ID が得られず、操作結果も不明な場合があります。
• 認証情報やメッセージ全文ではなく、構造化されたエラーコードを記録します。

保存すべきリクエスト ID はどれか

API の概要に追跡の仕様があります。同じヘッダー名でも、送信方向によって役割が異なります。

値	取得元	用途
独自の X-Request-Id	クライアントのリクエストヘッダー	自分のログから HTTP 試行を探す
client_request_id	JSON 応答に返されるクライアントの値	応答を該当試行に結び付ける
request_id	サーバーの JSON 応答	サポートへサーバー側の参照 ID を伝える
応答の X-Request-Id	サーバーの応答ヘッダー	本文がない場合も追跡情報を残す
data.message_id	送信成功時に返されるメッセージ識別子	HTTP リクエストではなくメッセージを識別する

6 月の API 更新記事ではフィールドを紹介しました。本記事の目的は、すべての結果分岐で情報を取りこぼさない実装です。

「承認済みの返信を 1 件送る」といった業務操作にはアプリ側の操作 ID を割り当て、HTTP 試行ごとに別のローカル ID を発行して関連を保存する設計を推奨します。これは独自の管理方式であり、追加の UnifyPort リクエストフィールドではありません。ID に顧客名、電話番号、本文、認証情報を含めないでください。

自動リトライを追加せずに 1 回の呼び出しを記録する

まずは読み取り専用の現在のワークスペース取得で試します。次の Node.js コードは組み込みの fetch と、バックエンド環境変数 UNIFYPORT_API_KEY を使用します。ログには許可した診断項目だけを出力し、リクエストヘッダーや応答本文は出しません。

タイムアウト値はクライアント側の設定例で、サービスの制限値ではありません。関数はアプリケーションレベルで 1 回だけ呼び出し、元の Response を呼び出し元に返します。

import { randomUUID } from 'node:crypto';

async function tracedWorkspaceRead(apiKey, operationId) {
  const clientAttemptId = randomUUID();
  const startedAt = new Date().toISOString();
  const startedMs = Date.now();
  let response;

  try {
    response = await fetch('https://api.unifyport.ai/v1/workspace', {
      headers: {
        'X-Api-Key': apiKey,
        'X-Request-Id': clientAttemptId
      },
      signal: AbortSignal.timeout(10000)
    });
  } catch {
    console.info({
      operation_id: operationId,
      client_attempt_id: clientAttemptId,
      started_at: startedAt,
      elapsed_ms: Date.now() - startedMs,
      outcome: 'no_http_response'
    });
    throw new Error('No HTTP response; inspect the local attempt record');
  }

  const headerId = response.headers.get('X-Request-Id');
  const body = response.status === 204
    ? null
    : await response.clone().json().catch(() => null);

  console.info({
    operation_id: operationId,
    client_attempt_id: clientAttemptId,
    started_at: startedAt,
    elapsed_ms: Date.now() - startedMs,
    http_status: response.status,
    server_request_id_header: headerId,
    server_request_id_body: body?.request_id ?? null,
    echoed_client_request_id: body?.client_request_id ?? null,
    error_code: body?.error?.code ?? null,
    numeric_code: body?.error?.numeric_code ?? null
  });
  return response;
}

const apiKey = process.env.UNIFYPORT_API_KEY;
if (!apiKey) throw new Error('Configure UNIFYPORT_API_KEY');
await tracedWorkspaceRead(apiKey, randomUUID());

operation_id や outcome はローカルログ用のフィールドで、API 応答のスキーマではありません。204 分岐は、本文なしと定義された操作にも処理を転用できるようにしています。ワークスペース取得自体は成功時に 200 を返します。空の応答はローカルモックで試し、ログの確認だけを目的にアカウントを削除しないでください。

ヘッダーと本文の両方を残すと、値の欠落や不一致を確認できます。中継サービスからの応答は API の形式に従わない場合があります。その場合も HTTP ステータスとローカル試行を保存し、サーバー ID を作り上げないことが重要です。本番では解析対象とログのサイズを制限し、アクセス権と保存期間も定めてください。

調査に使える障害報告にまとめる

エラーリファレンスは error.code、error.numeric_code、error.message を定義しています。処理の分岐には説明文ではなく code または numeric_code を使います。数値コードは、既存コードや HTTP ステータスを変えずに上流側の原因を細かく示すことがあります。

観測結果	保存する証拠	次の判断
JSON の成功・エラー応答	ステータス、サーバー ID、クライアント値、エラーコード	エンドポイントの意味に沿って解釈する
本文なしの 204	ステータスと応答 X-Request-Id	JSON がないことを API 障害にしない
本文を解析できない・形式が異なる	ステータス、取得できたヘッダー ID、ローカル ID	応答経路を調べる
HTTP 応答なし	ローカル ID、開始時刻、業務操作	照合まで結果不明として扱う

サポートへの報告には、環境、UTC 時刻、HTTP メソッドとルートテンプレート、取得できたサーバー ID、ローカル試行 ID、ステータスとエラーコード、期待した動作と実際の動作を含めます。アカウントや会話の識別子は適切な制限付きの窓口で共有してください。API キー、セッション情報、署名シークレット、返信トークン、アクセス署名付きメディア URL は除外します。

X Chat のトラブルシューティングは、この記録を使ってアカウント全体の問題と特定会話の問題を切り分ける例です。リクエスト ID は証拠を探す手掛かりであり、それ自体が原因を説明するわけではありません。

追跡 ID をリトライの許可にしない

POST /v1/messages に同じクライアント ID を再送しても、冪等性が保証されるとは記載されていません。送信がタイムアウトした場合、応答がなくても操作が実行済みの可能性があります。まず結果不明と記録し、その後に再送を判断します。

LINE 連携では特に、明示的なリトライキー仕様と混同しないでください。LINE は重複受け付け応答に x-line-accepted-request-id を返すと定義しています。似た名前の UnifyPort ヘッダーから同じ挙動を推測することはできません。別の実装手順は LINE リトライキーガイドを参照してください。

Webhook も別の相関管理です。配信リファレンスの X-Device-Delivery-Id は X-Device-Event-Id にフォールバックすることがあり、HTTP 試行ごとの一意性は保証されません。REST とイベントに ID があるだけで両者を結び付けないでください。受信試行を一意に記録したければローカル ID を発行します。重複排除は HistorySync の例外も含むイベント別の規則に従い、ログとは独立して実装します。

FAQ

削除に成功したのに request_id がないのはなぜですか？

成功した 204 は JSON 本文を持ちません。応答の X-Request-Id ヘッダーを読みます。

request_id で送信状態を取得できますか？

追跡仕様にはリクエスト状態の照会エンドポイントはありません。実際の結果を保存し、サポートされる証拠で不明な操作を照合してください。ID から新しい URL を組み立てないでください。

client_request_id は冪等性キーですか？

その保証は記載されていません。クライアントの値を返す相関用フィールドであり、重複送信防止ではありません。

次のステップと出典

既存の API クライアントに診断サマリーを追加し、JSON エラー、空の応答、不正な本文、ネットワーク障害をローカルモックで試してください。分岐の基準はエラーリファレンスです。

確認日：2026-10-01。

• UnifyPort：API 概要とリクエスト追跡
• UnifyPort：エラーリファレンス
• UnifyPort：Webhook 配信
• LINE：失敗した API リクエストの再試行