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

errors appears only when two or more fields fail at once. One failing field returns the flat envelope instead: the specific code at the top level, the field name in field, and no errors array.

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

Two or more failing fields collapse the top-level code to validation_failed and list each one:

{"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 names the value that failed validation, which is not always spelled like the request field — address can come back as target_address. Branch on code; read field as a hint for your logs.

Common codes

Code	HTTP	Action
malformed_request	400	Fix JSON and field types.
field_invalid_format	400	One field failed; read field and correct it.
validation_failed	400	Two or more fields failed; read errors.
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.
energy_price_changed	409	Fetch a new quote and submit again; no order and no hold were created.
insufficient_balance	409	Top up the account balance before retrying.
energy_intake_disabled	409	New orders are paused; retry later.
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.

A 401 also carries a more specific code when the request got far enough to name one: authorization_missing, authorization_malformed, timestamp_missing, timestamp_expired, invalid_credentials, or ip_not_allowed. The action is the same for all of them — repair the signature or the credential, and do not retry the request unchanged.

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