API-Fehler

Jeder API-Fehler kommt mit Content-Type: application/problem+json und folgt RFC 9457 Problem Details. Die Energy API kennt kein zweites Fehlerformat.

Umschlag

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

Feld	Typ	Zweck
type	string	Stabile URI des Fehlertyps.
title	string	Kurze HTTP-Kategorie.
status	integer	Der im Body wiederholte HTTP-Statuscode.
detail	string	Gefahrlos lesbare Erklärung für Menschen.
code	string	Stabiler Maschinencode für die Anwendungslogik.
field	string oder null	Das eine ungültige Feld, sofern zutreffend.
errors	array oder null	Mehrere Feldfehler mit code, field und message.

Verzweigen Sie Ihre Logik über code. detail dürfen Sie im Betrieb als Rückfalltext anzeigen, aber niemals programmatisch auswerten.

Mehrere Feldfehler

errors erscheint nur, wenn zwei oder mehr Felder gleichzeitig ungültig sind. Bei einem einzelnen ungültigen Feld kommt der flache Umschlag: der konkrete Code auf oberster Ebene, der Feldname in field, kein 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"}

Ab zwei ungültigen Feldern wird der Code auf oberster Ebene zu validation_failed, und jedes Feld wird einzeln aufgeführt:

{"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 benennt den geprüften Wert, und dessen Name entspricht nicht immer dem Feld der Anfrage: address kommt als target_address zurück. Verzweigen Sie über code und lesen Sie field als Hinweis für Ihre Protokolle.

Häufige Codes

Code	HTTP	Vorgehen
malformed_request	400	JSON und Feldtypen korrigieren.
field_invalid_format	400	Ein Feld ist ungültig; field lesen und korrigieren.
validation_failed	400	Zwei oder mehr Felder sind ungültig; errors lesen.
unauthorized	401	HMAC, Zeitstempel und Zugangsdaten prüfen.
energy_order_not_found	404	Bestellung als nicht verfügbar behandeln; die Zugehörigkeit wird nicht offengelegt.
energy_order_idempotency_conflict	409	Dieselbe ID nicht für eine andere Bestellung verwenden.
energy_price_changed	409	Neues Angebot einholen und erneut senden; es wurde keine Bestellung angelegt und kein TRX reserviert.
insufficient_balance	409	Vor dem nächsten Versuch das Kontoguthaben aufladen.
energy_intake_disabled	409	Neue Bestellungen sind ausgesetzt; später erneut senden.
payload_too_large	413	Anfragetext verkleinern.
unsupported_media_type	415	application/json senden.
rate_limited	429	Retry-After beachten.
energy_api_unavailable	503	Mit wachsendem Abstand wiederholen.

Kam die Anfrage weit genug, um die Ursache zu benennen, trägt ein 401 zusätzlich einen genaueren Code: authorization_missing, authorization_malformed, timestamp_missing, timestamp_expired, invalid_credentials oder ip_not_allowed. Das Vorgehen ist bei allen gleich — Signatur oder Zugangsdaten reparieren und die Anfrage nicht unverändert wiederholen.

Sichere Fehlerbehandlung

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