API hataları

Her API hatası Content-Type: application/problem+json ile ve RFC 9457 Problem Details biçiminde gelir. Energy API'nin başka hata zarfı yoktur.

Zarf

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

Alan	Tür	Amaç
type	string	Kararlı hata türü URI'si.
title	string	Kısa HTTP kategorisi.
status	integer	Gövdede de yer alan HTTP durum kodu.
detail	string	İnsan için güvenli açıklama.
code	string	Uygulama dallanması için kararlı makine kodu.
field	string veya null	Varsa hatalı tek alan.
errors	array veya null	code, field, message içeren alan hataları.

Uygulama mantığını code üzerinden kurun. detail operatöre yedek metin olarak gösterilebilir, ancak programatik olarak ayrıştırılmamalıdır.

Birden fazla alan hatası

errors yalnızca aynı anda iki veya daha fazla alan hatalıysa döner. Tek alan hatalıysa yanıt düz gelir: üst düzeyde ilgili kod, alan adı field içinde ve errors dizisi yok.

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

İki alandan itibaren üst düzey kod validation_failed olur ve her alan ayrı ayrı listelenir:

{"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, doğrulamadan geçemeyen değeri adlandırır ve bu ad her zaman istekteki alan adıyla aynı olmaz: address, target_address olarak döner. Uygulama mantığını code üzerinden kurun, field değerini günlükleriniz için ipucu olarak okuyun.

Yaygın kodlar

Kod	HTTP	İşlem
malformed_request	400	JSON'u ve alan türlerini düzeltin.
field_invalid_format	400	Tek alan hatalıdır; field değerini okuyup düzeltin.
validation_failed	400	İki veya daha fazla alan hatalıdır; errors değerini okuyun.
unauthorized	401	HMAC'i, zaman damgasını ve kimlik bilgisini kontrol edin.
energy_order_not_found	404	Siparişi kullanılamaz kabul edin; sahiplik açıklanmaz.
energy_order_idempotency_conflict	409	Aynı kimliği başka siparişte kullanmayın.
energy_price_changed	409	Yeni teklif alıp yeniden gönderin; sipariş veya TRX blokesi oluşturulmamıştır.
insufficient_balance	409	Yeniden denemeden önce hesap bakiyesini yükleyin.
energy_intake_disabled	409	Yeni sipariş alımı duraklatıldı; daha sonra yeniden gönderin.
payload_too_large	413	İstek gövdesini küçültün.
unsupported_media_type	415	application/json gönderin.
rate_limited	429	Retry-After değerine uyun.
energy_api_unavailable	503	Artan beklemeyle yeniden deneyin.

İstek nedeni adlandıracak kadar ilerlediyse 401 yanıtı daha belirli bir kod da taşır: authorization_missing, authorization_malformed, timestamp_missing, timestamp_expired, invalid_credentials veya ip_not_allowed. Hepsinde işlem aynıdır: imzayı ya da kimlik bilgisini düzeltin, isteği değiştirmeden yeniden göndermeyin.

Güvenli işleyici

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