Ошибки API

Каждая ошибка API возвращается с Content-Type: application/problem+json и соответствует RFC 9457. Другого формата ошибок у 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	Считать заказ недоступным; чужой ID не раскрывается.
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 ?? []);
}