API 错误

每个 API 错误都使用 Content-Type: application/problem+json 和 RFC 9457 Problem Details。Energy API 没有其他错误包装格式。

错误包装

{"type":"https://rentron.xyz/docs/errors/codes#energy_order_not_found","title":"Not Found","status":404,"detail":"Order was not found.","code":"energy_order_not_found"}

字段	类型	用途
type	string	稳定的错误类型 URI。
title	string	简短的 HTTP 类别。
status	integer	在响应体中重复的 HTTP 状态码。
detail	string	可安全显示给人的说明。
code	string	供程序分支使用的稳定机器码。
field	string 或 null	适用时的单个无效字段。
errors	array 或 null	含有 code、field、message 的多个字段错误。

应用逻辑应依据 code 分支。可以把 detail 作为给操作人员的兜底文本，但绝不能按它解析程序逻辑。

多字段错误

只有同时有两个或更多字段校验失败时才会返回 errors。只有一个字段失败时返回扁平结构：顶层是该字段对应的错误码，字段名放在 field，没有 errors 数组。

{"type":"https://rentron.xyz/docs/errors/codes#field_invalid_format","title":"Bad Request","status":400,"detail":"Request validation failed.","code":"field_invalid_format","field":"address"}

两个字段起，顶层错误码收敛为 validation_failed，每个字段单独列出：

{"type":"https://rentron.xyz/docs/errors/codes#validation_failed","title":"Bad Request","status":400,"detail":"Request validation failed.","code":"validation_failed","errors":[{"code":"field_invalid_format","field":"target_address","message":"Request validation failed."},{"code":"field_must_be_positive","field":"duration_minutes","message":"Request validation failed."}]}

field 指的是校验失败的那个值，名称不一定和请求字段一致：address 会以 target_address 返回。程序分支依据 code，field 只作为排查日志的线索。

常见错误码

错误码	HTTP	处理方式
malformed_request	400	修正 JSON 和字段类型。
field_invalid_format	400	单个字段校验失败；读取 field 并修正该字段。
validation_failed	400	两个或更多字段校验失败；读取 errors。
unauthorized	401	检查 HMAC、时间戳和凭证。
energy_order_not_found	404	视为订单不可用；不会泄露归属。
energy_order_idempotency_conflict	409	不要把同一 ID 用于另一笔订单。
energy_price_changed	409	获取新报价后重新提交；订单未创建，TRX 未冻结。
insufficient_balance	409	重试前先给账户余额充值。
energy_intake_disabled	409	新订单已暂停受理；稍后重新提交。
payload_too_large	413	减小请求体。
unsupported_media_type	415	发送 application/json。
rate_limited	429	遵守 Retry-After。
energy_api_unavailable	503	使用退避重试。

如果请求已经走到能判定具体原因的一步，401 还会带上更精确的错误码：authorization_missing、authorization_malformed、timestamp_missing、timestamp_expired、invalid_credentials 或 ip_not_allowed。处理方式相同：修好签名或凭证，不要原样重发请求。

安全处理方式

if (!response.ok) {
  const problem = await response.json();
  if (response.status === 429) scheduleRetry(response.headers.get('Retry-After'));
  throw new RentronApiError(problem.code, problem.detail, problem.errors ?? []);
}