Hatalar

Her 4xx/5xx yanıtı aynı JSON zarfını taşır:

{
  "code": 400,
  "message": "invalid_input",
  "details": [
    { "field": "items[0].unit_price", "message": "must be a positive decimal string" }
  ]
}

• code — sayısal HTTP durumu (400, 401, 404, …). Genel HTTP-katmanı işleme için kullanışlıdır, ancak dallanma mantığı için bunun yerine message üzerinde switch yapın — code örneğin invalid_input ile payment_method_not_supported (her ikisi de 400) arasında ayrım yapmaz.
• message — lower-snake-case sentinel adı (örn. INVALID_INPUT "invalid_input" olur). Sürümler arasında stabildir — bunun üzerinde switch yapın.
• details — doğrulama hatalarında doldurulur. İstemcinin hataları girdilere sabitlemesi için { field, message } nesnelerinden oluşan dizi. Aksi takdirde atlanır.

{ "error": "unauthorized", "message": "invalid signature" }

HTTP durumu → tipik kodlar

Tam kod referansı

Görebileceğiniz code değerleri:

Kimlik doğrulama (401)

• INVALID_CREDENTIALS — API anahtarı kombinasyonu reddedildi
• INVALID_TOKEN — token ayrıştırılamadı veya değiştirilmiş
• TOKEN_EXPIRED — token süresi doldu
• SESSION_EXPIRED — panel oturumunun süresi doldu
• INVALID_SIGNATURE — B2B / webhook çağrılarında HMAC imza uyumsuzluğu

Yetkilendirme (403)

• FORBIDDEN — doğrulandınız, ancak bu eylemi gerçekleştirme izniniz yok
• IP_BLOCKED — bu IP adresinden gelen istekler engellendi

Bulunamadı (404)

• NOT_FOUND — genel
• RECORD_NOT_FOUND — verilen ID için satır eksik

Çakışma (409)

• ALREADY_EXISTS — genel

Doğrulama (400)

• INVALID_INPUT — genel; details’i kontrol edin
• MISSING_REQUIRED — gerekli bir alan eksik
• INVALID_FORMAT — değer beklenen formatla eşleşmedi (örn. UUID, URL, e-posta)
• INVALID_LENGTH — değer çok kısa veya çok uzun
• INVALID_VALUE — değer izin verilen enum/aralığın dışında
• PAYMENT_METHOD_NOT_SUPPORTED — provider/varlık kombinasyonu satıcı için etkin değil
• AMOUNT_BELOW_MINIMUM — sipariş tutarı ağ başına veya env-seviyesi zemininin altında. Yanıtın details.floor_usd alanı yapılandırılmış zemini (USD) taşır, böylece onu doğrudan yüzeye çıkarabilirsiniz; message metni de bunu belirtir.
• INSUFFICIENT_BALANCE — alıcının cüzdanı, transferi karşılamak için yeterli ödeme varlığını tutmuyor.
• INSUFFICIENT_GAS — alıcının cüzdanında transferi yaymak için yerel gas eksik.

Ödeme / faturalama (402)

• INSUFFICIENT_CREDIT — satıcı ön ödemeli bakiyesi ağ ücretini (gas) / platform ücretini karşılayamaz. Panel üzerinden yükleyin, ardından yeniden deneyin

Rate limit (429)

• TOO_MANY_REQUESTS — IP rate limit’i aşıldı
• TOO_MANY_ATTEMPTS — aynı kaynak üzerinde (örn. OTP) tekrar eden başarısız denemeler bir throttle’ı tetikledi

Sunucu hataları (500)

• EXTERNAL_SERVICE_ERROR — bir üçüncü taraf provider başarısız oldu
• INTERNAL_SERVER_ERROR — beklenmedik hata; yanıt Date başlığı ve X-RateLimit-* başlıklarıyla destek ekibine ulaşın

Kullanılabilirlik (503)

• SERVICE_UNAVAILABLE — servis geçici olarak kullanılamıyor; geri çekilmeyle yeniden deneyin

Doğrulama hataları (400)

Sorun hatalı biçimlendirilmiş bir istek gövdesi olduğunda, details bir dizidir, böylece hataları alanlara geri eşleyebilirsiniz:

{
  "code": 400,
  "message": "invalid_input",
  "details": [
    { "field": "items[0].unit_price", "message": "must be a positive decimal string" },
    { "field": "success_url", "message": "must be a valid https URL" }
  ]
}

Auth hataları (401)

INVALID_SIGNATURE’ın üç yaygın nedeni vardır:

• Yanlış secret anahtar (env var’ı yeniden kontrol edin)
• Timestamp sapması > 5 dk (NTP senkronize edin)
• Yanlış kanonik dize (en sık: \n ayraçlarını unutmak veya ayrıştırılıp-sonra-yeniden-stringleştirilmiş, gönderdiğinizden farklı bir gövdeyi imzalamak)

Tam imzalama algoritması için Kimlik doğrulama sayfasına bakın.

Rate limit’ler (429)

X-RateLimit-Limit ve X-RateLimit-Remaining, rate limit’e takılan her yanıta eklenir, yalnızca başarılı olanlara değil. Bunları IP’niz için canlı bütçe olarak değerlendirin.

Rate-limit’li yanıtlar bir Retry-After başlığı içerir (pencerenin sıfırlanmasına kalan saniye) — buna uyun. Yedek olarak, jitter ile geri çekilin — 1s temel + 30s’ye üstel artan bekleme süresi.

Yetersiz kredi (402)

INSUFFICIENT_CREDIT (HTTP 402 Payment Required), ön ödemeli bakiyenizin, gerçekleştirmeye çalıştığınız işlem için ağ ücretini (gas) ve platform ücretini karşılayamadığı anlamına gelir; tipik olarak bir kripto ödemesinin tahsil edilmesi veya ağ ücreti karşılanan bir zincir üstü eylem. Satıcı panelinden (Faturalama → Kredi ekle) yükleyin, ardından işlemi yeniden deneyin. Devam etmekte olan işlemler bakiye yüklendiğinde otomatik olarak sürer.

Sunucu hataları (5xx)

Bir 500, isteği işleyemediğimiz anlamına gelir. Geri çekilme ile yeniden deneyin — idempotency_key’iniz, orijinal istek kısmen başarılı olmuş olsa bile çift ücretlendirme yapmamanızı sağlar.

Yeniden denemeler bir dakika içinde kurtarılmazsa, alıcıya genel bir “ödeme geçici olarak kullanılamıyor” gösterin ve başarısız uç noktayı, satıcı ID’nizi, yanıt Date başlığını ve X-RateLimit-* değerlerini ve yaklaşık istek zamanını destek ekibine iletin — bu, isteği bulmamız için yeterlidir.

Webhook teslim hataları

Webhook teslimleri ayrı bir başarısızlık kanalıdır — API hatası olarak yüzeye çıkmazlar çünkü sunucunuz çağrı yapan taraf değildir. Bir teslim 2xx-olmayan bir yanıt döndürdüğünde (veya zaman aşımına uğradığında), üstel artan bekleme süresi ile 0s, 1dk, 5dk, 15dk, 1s, 6s aralıklarında yeniden denenir (toplam altı deneme, Webhook’lar → Genel bakış ile aynı program). Tam teslim başına geçmiş, panelin Geliştiriciler → Webhook’lar → [uç nokta] → Teslim günlüğü altında görünür. Altıncı denemeden sonra teslim panelde “Başarısız” olarak işaretlenir ve sunucunuz sağlıklı olduğunda manuel olarak yeniden oynatabilirsiniz.