Ошибки 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 можно показать оператору как запасной текст, но нельзя разбирать программно.

Ошибка нескольких полей

{"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	Считать заказ недоступным; чужой ID не раскрывается.
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 ?? []);
}