API errors

Every API error uses Content-Type: application/problem+json and RFC 9457 Problem Details. Energy API has no alternate error envelope.

Envelope

{"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"}

Field	Type	Purpose
type	string	Stable error-type URI.
title	string	Short HTTP category.
status	integer	HTTP status code repeated in the body.
detail	string	Safe human-readable explanation.
code	string	Stable machine code for application branching.
field	string or null	One invalid field, when applicable.
errors	array or null	Multiple field errors with code, field, and message.

Branch application logic on code. You may show detail to an operator as a fallback, but never parse it.

Multiple field errors

{"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."}]}

Common codes

Code	HTTP	Action
malformed_request	400	Fix JSON and field types.
validation_failed	400	Read field/errors and correct input.
unauthorized	401	Check HMAC, timestamp, and credential.
energy_order_not_found	404	Treat the order as unavailable; ownership is not disclosed.
energy_order_idempotency_conflict	409	Do not reuse one ID for another order.
payload_too_large	413	Reduce the request body.
unsupported_media_type	415	Send application/json.
rate_limited	429	Respect Retry-After.
energy_api_unavailable	503	Retry with backoff.

Safe handler

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