Hatalar ve Reddetme Nedenleri

Hata kodları ve reddetme nedenlerinin eksiksiz kataloğu.

Hata Yanıt Formatı

HTTP Hata Yanıtları (Middleware)

Middleware'den gelen yapılandırılmış JSON hataları (HTTP 4xx/5xx):

{
  "error": "<code>",
  "message": "<human message>"
}

Motor Seviyesi Reddetmeler (HTTP 200)

İşlem reddetmeleri, OrderUpdateMessage.status = "REJECTED" ile HTTP 200 döndürür:

{
  "timestamp": 1735000000000,
  "info": { ... },
  "status": "REJECTED",
  "reason": "<exact rejection string>",
  "filled_size": 0,
  "order_id": null,
  "wallet_address": "0x...",
  "mmp_triggered": false
}

Kritik: İşlem reddetmeleri için HTTP durum kodlarına güvenmeyin. Her zaman status ve reason alanlarını kontrol edin.

Middleware Hata Kodları

Bunlar, yapılandırılmış JSON gövdesiyle HTTP hata yanıtları olarak döndürülür.

Kod	HTTP Durumu	Açıklama
invalid_request	400	İstek gövdesi okunamıyor
invalid_json	400	JSON ayrıştırma başarısız oldu
missing_field	400	Gerekli alan eksik
invalid_wallet	400	Cüzdan dizesi ayrıştırılamadı
invalid_parameter	400	Geçersiz parametre (örneğin, size/price dize olmalıdır)
signature_verification_failed	400	EIP-712 imza kurtarma başarısız oldu
unsupported_endpoint	400	Middleware bu yolu desteklemiyor
unauthorized	401	İmzalayan cüzdan için yetkili değil (agent kimlik doğrulaması başarısız oldu)
internal_error	500	Agent yetkilendirme kontrolü beklenmedik şekilde başarısız oldu

Motor Reddetme Nedenleri

Bunlar, status="REJECTED" olduğunda OrderUpdateMessage.reason alanında görünür.

Vadesi Dolmuş Enstrüman

Neden: "Instrument has expired"

Sebep: Vadesi zaten dolmuş bir enstrüman üzerine emir verilmesi.

Aksiyon: Enstrüman vade sonunu GET /instruments veya GET /markets üzerinden kontrol edin.

Fonlanmamış Hesap

Neden: "Account has no funds. Please deposit before trading."

Sebep: Hesap nakit bakiyesi <= 0.0 durumunda.

Aksiyon: İşlem yapmadan önce cüzdana USDC yatırın.

Yetersiz Teminat

Neden: "Insufficient margin: required={:.2}, available={:.2}, shortfall={:.2}"

Örnek: "Insufficient margin: required=1500.00, available=1200.00, shortfall=300.00"

Sebep: İşlem öncesi teminat kontrolü, önerilen emir sonrasında mevcut teminatın (özsermayenin) teminat gereksinimini karşılamaya yetersiz olduğunu tespit etti.

Standart Marjin hesapları için gerekli teminat; opsiyon tarafına, opsiyon türüne, kullanım fiyatına, dayanak varlık fiyatına ve mevcut portföye bağlıdır. Güncel lansman teminat modeli için Standard Margin sayfasına bakın.

Aksiyon:

1. Portföyü GET /portfolio?wallet=... üzerinden kontrol edin
2. Teminat hesaplamasını Margin sayfasında inceleyin
3. Pozisyon büyüklüğünü azaltın veya teminat ekleyin

Eksik Spot Fiyat

Neden: "Failed to get portfolio: No spot price available for underlying: {underlying}"

Sebep: Motor, gerçekleşmeleri simüle etmek için gereken dayanak varlığın spot fiyatını belirleyemiyor.

Aksiyon: Hyperliquid spot fiyat akışı bağlantısını kontrol edin. Spot fiyatlar allMids WebSocket akışından gelir.

Kademe Kısıtlamaları

Neden: "Tier1 users cannot go short. Filled long position: {filled}, total sell orders (including new): {total} (symbol: {symbol})"

Sebep: Cüzdan tier1 (yalnızca uzun pozisyon) seviyesindedir ve yeterli gerçekleşmiş uzun pozisyon olmadan satış yapmaya çalışılmıştır.

Aksiyon:

1. Kademeyi GET /user-tier?wallet=... üzerinden kontrol edin
2. Tüm satışların gerçekleşmiş uzun pozisyonlarla karşılandığından emin olun
3. Bir piyasa yapıcı entegrasyonu için yazıcı erişimine ihtiyacınız varsa Hypercall ile iletişime geçin

Geçersiz Sembol

Neden: "Invalid symbol: {symbol}"

Sebep: Sembol için bir emir defteri mevcut değil.

Aksiyon:

1. Piyasanın var olduğunu GET /instrument-specs ve GET /markets üzerinden doğrulayın
2. Sembol formatını kontrol edin: UNDERLYING-YYYYMMDD-STRIKE-(C|P)

Sembol Ayrıştırma Hatası

Neden: "Failed to parse symbol: {detail}"

Sebep: Sembol beklenen formatla eşleşmiyor.

Aksiyon: Sembol formatının UNDERLYING-EXPIRY-STRIKE-(C|P) veya Deribit tarzı DDMMMYY ile eşleştiğini doğrulayın.

İptal Hataları

Emir Bulunamadı

Neden: "Order not found for cancellation: {client_id}"

Sebep: Belirtilen client_id ile emir bulunamadı.

Aksiyon: client_id değerinin doğru olduğunu ve emrin var olduğunu GET /orders?wallet=... üzerinden doğrulayın.

Emir Defteri Bulunamadı

Neden: "Orderbook not found for symbol: {symbol}"

Sebep: Sembol için emir defteri mevcut değil.

Aksiyon: Sembolün geçerli olduğunu ve piyasanın var olduğunu doğrulayın.

Emir Emir Defterinde Değil

Neden: "Order {id} not found in orderbook {symbol}"

Sebep: Emir ID'si mevcut ancak emir emir defterinde değil (gerçekleşmiş/iptal edilmiş olabilir).

Aksiyon: Emir durumunu GET /orders?wallet=... üzerinden kontrol edin.

Emir Zaten Gerçekleşmiş

Neden: "Order {id} is already filled and cannot be cancelled"

Sebep: Emir, iptal isteğinden önce tamamen gerçekleşti.

Aksiyon: Emir durumunu GET /orders?wallet=... üzerinden kontrol edin.

Emir Zaten İptal Edilmiş

Neden: "Order {id} was already cancelled"

Sebep: Emir zaten iptal edilmişti.

Aksiyon: Emir durumunu GET /orders?wallet=... üzerinden kontrol edin.

Perp Emir Doğrulaması

Neden: "Perp order missing underlying symbol"

Sebep: Perp emri underlying alanını içermiyor.

Aksiyon: Perp emrinin underlying sembolünü içerdiğinden emin olun.

MMP Tetiklendi

Neden: "MMP triggered during fill processing"

Sebep: Gerçekleşme işlenirken MMP limitleri aşıldı. Emir kısmen gerçekleşti, ardından MMP tetiklendi ve kalan miktarı iptal etti.

Aksiyon:

1. MMP yapılandırmasını GET /mmp-config?wallet=...&currency=... üzerinden kontrol edin
2. Gerçekleşme penceresi metriklerini inceleyin
3. MMP limitlerini ayarlayın veya POST /mmp-config/reset ile MMP durumunu sıfırlayın

MMP anlambiliminin tamamı için MMP sayfasına bakın.

MMP İptali (Diğer Emirler)

Neden: "Order canceled by MMP trigger"

Sebep: Aynı cüzdan+dayanak varlık için başka bir emrin MMP'yi tetiklemesi nedeniyle emir iptal edildi.

Aksiyon: MMP yapılandırmasını ve gerçekleşme aktivitesini inceleyin.

Handler Seviyesi Doğrulama Hataları

Bunlar, motora ulaşmadan önce HTTP 400 döndürür.

Fiyat Doğrulaması

Hata: "Price validation failed: Price {price} has {n} significant figures, maximum allowed is 5"

Sebep: Fiyat 5 anlamlı basamağı aşıyor.

Aksiyon: Fiyatı ≤ 5 anlamlı basamağa yuvarlayın.

Büyüklük/Fiyat Formatı

Hata: "Size must be greater than 0" veya "Price must be greater than 0"

Sebep: Büyüklük veya fiyat <= 0 durumunda ya da float olarak ayrıştırılamıyor.

Aksiyon: size ve price değerlerinin geçerli pozitif sayılar (dize olarak) olduğundan emin olun.

Geçersiz Sembol Formatı

Hata: Handler hata mesajıyla HTTP 400

Sebep: Sembol geçerli bir opsiyon sembolü olarak ayrıştırılamıyor.

Aksiyon: Sembol formatını doğrulayın: UNDERLYING-YYYYMMDD-STRIKE-(C|P).

Toplu Emir Hataları

Toplu uç noktalar, BulkOrderResult.error içinde öğe bazında hatalar döndürür:

• "Signature verification failed: ..."
• "Unauthorized: signer not authorized for wallet"
• "Price validation failed: ..."
• "Size must be greater than 0"
• "Price must be greater than 0"
• "Failed to send order to engine"
• "No response from engine"

Her sonuç, index (istek dizisindeki konum) ve success boolean değeri içerir.

WebSocket Hataları

WebSocket kontrol mesajları:

{
  "type": "Error",
  "message": "Authentication required for this channel"
}

Yaygın hatalar:

• "Authentication required for this channel": ?wallet= olmadan özel kanala abone olunmaya çalışıldı
• "Client not found": Dahili hata (bağlantı koptu)

Hata İşleme En İyi Uygulamaları

1. Her zaman status alanını kontrol edin: İşlem reddetmeleri için HTTP durum kodlarına güvenmeyin
2. reason dizesini ayrıştırın: Programatik işleme için tam neden dizelerini kullanın
3. Toplu hataları ele alın: Toplu isteklerdeki her öğe için BulkOrderResult.error alanını kontrol edin
4. Yeniden deneme mantığı: REJECTED emirlerde yeniden denemeyin (önce altta yatan sorunu düzeltin)
5. Loglama: Reddetmelerde hata ayıklama için OrderUpdateMessage mesajının tamamını loglayın

Hata Kodu Referans Tablosu

Reddetme Nedeni	Kategori	HTTP Durumu	Aksiyon
Instrument has expired	Vade sonu	200	Vade sonunu kontrol edin, farklı bir enstrüman kullanın
Account has no funds...	Fonlama	200	Fon yatırın (uygulandığında)
Insufficient margin: ...	Teminat	200	Büyüklüğü azaltın, teminat ekleyin, portföyü kontrol edin
Failed to get portfolio: No spot price...	Veri	200	Hyperliquid akış bağlantısını kontrol edin
Tier1 users cannot go short...	Kademe	200	tier2'ye yükseltin veya satışları karşılayın
Invalid symbol: ...	Sembol	200	Piyasanın var olduğunu doğrulayın
Order not found for cancellation: ...	İptal	200	Emrin var olduğunu doğrulayın
Order {id} is already filled...	İptal	200	Emir zaten gerçekleşmiş
Order {id} was already cancelled	İptal	200	Emir zaten iptal edilmiş
MMP triggered during fill processing	MMP	200	MMP yapılandırmasını inceleyin, limitleri ayarlayın
Order canceled by MMP trigger	MMP	200	MMP yapılandırmasını inceleyin, limitleri ayarlayın
signature_verification_failed	Kimlik doğrulama	400	İmzayı ve dize kodlamasını kontrol edin
unauthorized	Kimlik doğrulama	401	Agent'ı onaylayın veya cüzdanla imzalayın
Price validation failed: ...	Doğrulama	400	Fiyatı ≤ 5 anlamlı basamağa yuvarlayın

Reddetmelerde Hata Ayıklama

1. Emir detaylarını kontrol edin: symbol, price, size, side değerlerinin doğru olduğunu doğrulayın
2. Portföyü kontrol edin: Mevcut pozisyonları ve nakdi görmek için GET /portfolio?wallet=...
3. Kademeyi kontrol edin: Kademe kısıtlamalarını doğrulamak için GET /user-tier?wallet=...
4. MMP'yi kontrol edin: MMP limitlerini incelemek için GET /mmp-config?wallet=...&currency=...
5. Piyasayı kontrol edin: Enstrümanın var olduğunu doğrulamak için GET /markets ve GET /instruments
6. Logları inceleyin: Sunucu logları ek bağlam içerebilir (API üzerinden erişilemez)

Referanslar

• Reddetme mantığı: işlem motorunda uygulanır
• Teminat kontrolleri: emir kabulünden önce uygulanır
• Kademe kontrolleri: cüzdan kademesi bazında uygulanır
• Handler doğrulaması: standart istek doğrulaması