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 作为给操作人员的兜底文本，但绝不能按它解析程序逻辑。

多字段错误

{"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":"address","message":"Request validation failed."}]}

常见错误码

错误码	HTTP	处理方式
malformed_request	400	修正 JSON 和字段类型。
validation_failed	400	读取 field/errors 后修正输入。
unauthorized	401	检查 HMAC、时间戳和凭证。
energy_order_not_found	404	视为订单不可用；不会泄露归属。
energy_order_idempotency_conflict	409	不要把同一 ID 用于另一笔订单。
payload_too_large	413	减小请求体。
unsupported_media_type	415	发送 application/json。
rate_limited	429	遵守 Retry-After。
energy_api_unavailable	503	使用退避重试。

安全处理方式

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 ?? []);
}