Hatalar

Hatalar her zaman RFC 9457 application/problem+json olarak gelir:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

Alanlarla bir doğrulama hatası:

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

Hata kodları

type URL'si bu listedeki ilgili maddeye götürür.

invalid_key

401. Anahtar yok, yanlış, iptal edilmiş veya süresi dolmuş. Authorization başlığını ve paneldeki anahtar durumunu kontrol edin.

forbidden_scope

403. Anahtar geçerli ancak gerekli kapsam eksik. Kapsamı ekleyin veya yeni bir anahtar oluşturun (Kimlik doğrulama).

forbidden

403. İşleme bu hesap veya kaynak için izin verilmiyor: örneğin ilan başka bir hesaba ait veya ajanstaki rol yetersiz. Neden detail içindedir.

insufficient_funds

402. Cüzdanda yeterli para yok, plan kotası tükendi, ödenmemiş bir borç var veya adil kullanım limitine ulaşıldı. Hangisi olduğunu code söyler: INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED vb. Bakiye yükleyin, borcu ödeyin veya planı değiştirin.

validation

400. İstek doğrulamayı geçemedi. Tam olarak neyin yanlış olduğu detail ve errors içindedir. İsteği düzeltin; değiştirmeden tekrarlamak anlamsızdır.

business_rule

422. İstek doğru biçimde ama yerine getirilemiyor: veri eksik, ilan uygun olmayan durumda, mülk türü desteklenmiyor vb. Neden detail içinde, makine kodu code içindedir.

payload_too_large

413. Gövde veya bir dosya limiti aşıyor. Boyut sınırları her araçta belirtilmiştir. Geçerli JSON olmayan bir gövde 400 validation alır.

range_not_satisfiable

416. Dosya indirmesindeki Range dosyanın dışında kalıyor. Dosya boyutu Content-Range: bytes */size başlığındadır.

rate_limited

429. İstek sıklığı limiti aşıldı. Retry-After kaç saniye diyorsa bekleyin, sonra tekrarlayın (Limitler ve ücretlendirme). code hangi limit olduğunu söyler: minute_limit (saniyeler) veya daily_limit (00:00 UTC'de sıfırlanır).

not_found

404. Bilinmeyen yol ya da var olmayan veya size ait olmayan bir kaynak. Başkasına ait bir kaynak bilerek, var olmayanla aynı yanıtı alır.

idempotency_conflict

409. Bu Idempotency-Key ile bir istek hâlâ çalışıyor. Bitmesini bekleyin ve aynı anahtarla tekrarlayın (İdempotans). Zaman aşımından (502 provider_error) sonra anahtar 15 dakika tutulur: tekrarlamadan önce sonucu kontrol edin; tutma süresinden sonraki bir tekrar ücretli işi yeniden çalıştırır. Hızlı değerleme zaman aşımından sonra anahtarı serbest bırakır: aynı anahtarla tekrarlayın. Bu anahtarla yapılan bir çağrının ödemesi hâlâ ayrılıyorsa da aynı 409 gelir (code RESERVE_IN_PROGRESS, RESERVE_BUSY) - daha sonra tekrarlayın; RESERVE_REF_TAKEN - anahtar tükendi, yenisini gönderin.

conflict

409. Kaynak bu işleme izin vermeyen bir durumda (örneğin bir ilanı bir ajanstan diğerine taşımak, yürürlükte komisyon sözleşmesi olan bir ilanı silmek). Neden detail içindedir. İsteği değiştirmeden tekrarlamayın.

service_unavailable

503. Araç geçici olarak kullanılamıyor. Hiçbir ücret alınmadı. Retry-After süresinden sonra tekrarlayın; GET /tools/status araçların güncel durumunu gösterir.

provider_error

502. İşi yapan hizmet başarısız oldu. Geçicidir: artan bir bekleme ile tekrarlayın. detail aracın zamanında yanıt vermediğini söylüyorsa iş yine de bitebilir ve ücretlendirilebilir: yeniden başlatmadan önce GET /works ile kontrol edin; hızlı değerlemeyi aynı Idempotency-Key ile tekrarlayın. Fotoğraf iyileştirme, site ve taslak sonuçları GET /works içinde tutulmaz: bunlar için 15 dakikalık tutma süresinin bitmesini bekleyin ve sonucu panelde veya ilanlarınız arasında kontrol edin.

internal_error

500. İç hata. Bir bekleme ile tekrarlayın; sürerse requestId ile destekle iletişime geçin.

Liste büyüyebilir. Bilinmeyen bir kodu HTTP sınıfının genel hatası olarak ele alın (4xx, istek sorunu; 5xx, hizmet arızası).

Neler tekrarlanır

Bir şey oluşturan istekleri tekrarlarken her zaman aynı Idempotency-Key değerini gönderin: böylece tekrar, işi ne iki kez çalıştırır ne de iki kez ücretlendirir.

İstisnalar

• Lead'in mevcut durumunun izin vermediği Swipe Match olayları (POST /match/leads/{id}/events), title: business_rule ve nedeni code içinde (client_event_rejected, invalid_transition, not_available) olacak şekilde 409 ile yanıtlanır.
• Ajans lead havuzu işlemleri (POST /leads/{id}/claim, POST /leads/{id}/return-to-pool) kişisel bir anahtarla veya yetersiz bir rolle title: forbidden ile 403 yanıtı verir.

Neler ücretlendirilmez

Reddedilen bir istek (herhangi bir 4xx veya 5xx yanıtı) API çağrısı harcamaz. Araç ücreti yalnızca kabul edilen iş için alınır. İstisna, zaman aşımından sonraki provider_error yanıtıdır: iş yine de bitip ücretlendirilebilir; yeniden başlatmadan önce GET /works ile kontrol edin (fotoğraf iyileştirme, site ve taslak: panelde veya ilanlarınız arasında).

İlgili makaleler

• Limitler ve ücretlendirme
• İdempotans
• Kimlik doğrulama