错误码与诊断

如果还没有确定故障阶段，先看常见问题。track() 返回不表示事件已送达；接收结果按数据校验核对。

接入排查

错误码与投递结果排查

输入固定错误码、验证原因或故障关键字，查看原因及下一步操作。排查不会自动更改授权、清除队列或重发事件。

常见排查项：

使用 verifyDelivery 前，请确认所用交付包提供该 API；不要仅凭版本号判断。此页不自动修改 SDK 状态。

当前状态说明

已有业务用户时不能通过 identify 静默换人。使用 switchUser 建立明确账号边界；安全退出使用 signOut，匿名旅程连续性由 clearUser 单独表达。

典型错误反模式 (Anti-Pattern)

await sdk.identify('user-A');
await sdk.identify('user-B'); // 已存在另一用户

公开 API 示例

await sdk.switchUser('user-B');

下一步操作

确认登录回调没有重复初始化 SDK。
账号切换使用 switchUser；退出时按业务语义选择 signOut 或 clearUser。

常见错误与处理

错误码	含义	建议处理
`INVALID_EVENT`	事件结构或 Tracking Plan 不符合要求	对照事件字段与数据字典修正；这是不可重试事件。
`INVALID_BATCH_RESPONSE`	2xx 响应缺少有效整批 ACK 语义，或无法与请求批次对应	保留事件并检查 Collector 响应是否符合整批 ACK 合同；不要仅凭 HTTP 状态码判断成功。
`PROJECT_KEY_REQUIRED` / `PROJECT_NOT_AUTHORIZED`	请求缺少有效项目凭据，或项目无权接收	检查 `endpoint`、公开 `projectKey` 及服务端项目配置。
`BATCH_PAYLOAD_TOO_LARGE`	序列化后的批次超过 Collector 限制	SDK 可拆分多事件批次；单事件过大时需缩小事件内容。
`EVENT_PAYLOAD_TOO_LARGE` / `REQUEST_TOO_LARGE`	单事件或请求超过接收上限	缩小事件内容；过大的单事件不会通过重试变小。
`RATE_LIMITED`、`REQUEST_TIMEOUT`、`SERVER_UNAVAILABLE`、`COLLECTOR_ERROR`	限流、超时或暂时性服务端故障	按 SDK 重试调度等待后重试；服务端提供有效 `Retry-After` 时会参与延迟计算。
`IDENTITY_USER_SWITCH_REQUIRES_RESET`	已绑定用户时试图直接切换到另一用户	调用 `switchUser()`；需要完整安全退出时调用 `signOut()`。
`IDENTITY_SYNC_STALE`	身份同步请求基于过期状态	SDK 按身份同步合同最多协调重试一次；连续冲突需检查并发身份操作。

HTTP 408、429、5xx 会保留事件重试；不可重试的 4xx 按投递规则处理，413 可拆分批次。完整规则见离线队列与重试。

读取运行状态

Web、Android 和 iOS 均可读取健康快照、导出诊断报告并读取近期诊断记录。下例使用 Web API；Android 和 iOS 的调用方式见对应 API 参考。

typescript

const health = sdk.getHealthSnapshot();
const report = sdk.exportDiagnostics();
const timeline = sdk.getDiagnosticsTimeline(50);

console.info({
  sdkVersion: health.sdkVersion,
  initialized: health.initialized,
  queueSize: health.queueSize,
  uploadFailures: health.uploadFailures,
  lastError: health.lastError,
  recentStatuses: timeline.map((entry) => entry.status),
});

排查时先看 initialized、consentStatus 和 lastDropReason，确认 SDK 是否接纳事件；再看 queueSize、pendingWrites 和 lastError，确认是否仍在等待发送。需要关联接收端日志时，可使用 lastUploadBatchId 和 lastUploadEventIds。队列数量不能证明事件已持久化或接收端已确认。

诊断报告会对已知敏感模式进行脱敏，但事件名、插件名、捕获键、错误摘要和事件 ID 仍可能包含接入方自定义内容。分享前请检查报告是否含业务敏感信息，并遵循组织的数据处理流程。不要将完整事件属性、用户身份值、访问令牌或 Secret 手工写入诊断日志。

导出诊断报告

Web 可使用下载与摘要辅助函数：

typescript

import { copyDiagnosticsSummary, downloadDiagnostics } from '@track-business/sdk-web';

await copyDiagnosticsSummary(sdk);
downloadDiagnostics(sdk, { filename: 'track-business-diagnostics.json' });

Android 与 iOS 可从 SDK 获取诊断报告，再由应用展示或分享。

supportNextSteps 提供建议检查项，不是服务端错误码。

验证 ACK 与接收结果

事件批量上传的 HTTP 2xx 仅在响应符合整批 ACK 合同时才会清除本地事件。支持两种响应：

Collector 包装响应包含数值 code: 200 与 data.status: "ACCEPTED"，由 SDK 按当前请求的 batchId 归一化；
兼容的平铺响应包含与请求匹配的 batchId 和显式 accepted: "all"。

其他 2xx 响应不会确认队列。请以接收端记录核对结果；lastError === null 不能证明事件已接收。

错误码与诊断 ​