Rate Limit & Hata Kodları

Invozon API, kötüye kullanımı önlemek ve adil paylaşımı sağlamak için token başına rate limit uygular. Limitler endpoint kategorisine göre değişir.

Standart limitler

Kategori	Limit	Pencere
Auth (/v1/auth/*)	5 istek	5 dakika · e-posta bazında
Auth (/v1/auth/*)	10 istek	5 dakika · IP bazında
Read (GET)	600 istek	1 dakika
Write (POST, PUT, DELETE)	200 istek	1 dakika
Bulk import (/v1/products/bulk)	5 istek	1 dakika
Webhook delivery (giden)	Sınırsız	—

Rate limit başlıkları

Her yanıtta:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1717228800

X-RateLimit-Reset epoch saniyesi (sıfırlama zamanı).

429 alınca ne yapmalı?

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "code": "rate_limit.exceeded",
    "message": "Saniyede çok fazla istek. 12 saniye bekleyin.",
    "retry_after": 12
  }
}

Retry-After başlığını kullan. Önerilen geri çekilme stratejisi: exponential backoff + jitter:

import time, random, requests

def request_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        r = requests.get(url, headers=headers)
        if r.status_code != 429:
            return r
        retry_after = int(r.headers.get("Retry-After", 2 ** attempt))
        wait = retry_after + random.uniform(0, 1)  # jitter
        time.sleep(wait)
    raise Exception("Rate limit aşıldı, deneme bitti.")

Hata kodu yapısı

Tüm hatalar JSON döner, yapısı tutarlıdır:

{
  "error": {
    "code": "domain.specific_code",
    "message": "Kullanıcıya gösterilebilir Türkçe açıklama.",
    "details": { ... },
    "request_id": "req_abc123"
  }
}

request_id her zaman vardır; destek ekibine iletilirse log'a hızlı erişim sağlar.

Yaygın hata kodları

HTTP	Code	Açıklama	Çözüm
400	validation.failed	Body geçersiz	details alanına bak, alanları düzelt
401	auth.token_expired	Token süresi doldu	Refresh token ile yenile
401	auth.token_invalid	Token bozuk veya revoke	Yeniden giriş yap
403	auth.insufficient_scope	Scope yetersiz	Token'da uygun scope iste
404	resource.not_found	Kaynak yok	ID/slug doğrula
409	resource.conflict	Çakışma (örn: aynı SKU iki kez)	Mevcut kaydı güncelle
422	business.invalid	İş kuralı ihlali	details alanına bak
429	rate_limit.exceeded	Limit aşıldı	Retry-After bekle, backoff uygula
500	server.internal	Sunucu hatası	request_id ile bize ulaş
502	marketplace.unreachable	Pazaryeri API erişilemez	Tekrar dene (kısa süre)
503	marketplace.rate_limited	Pazaryeri rate limit	Invozon otomatik kuyruğa alır

Pazaryeri rate limit yansıması

Trendyol/Hepsiburada/N11/Amazon TR'nin kendi rate limit'leri vardır. Invozon bu limitleri size yansıtır:

• Şeffaf kuyruklama: Sınıra yaklaşan istekler otomatik kuyruğa alınır
• Pazaryeri 429 → Invozon 503: Üst limite ulaşılırsa marketplace.rate_limited döner
• Retry-After her zaman doğru süreyi söyler

Bulk import için optimizasyon

5000+ ürün eklerken /v1/products/bulk endpoint'ini kullan — tek istekle 500 ürün, dakikada 5 istek = 2500 ürün/dakika.

POST /v1/products/bulk
Content-Type: application/json

{
  "products": [
    { "sku": "A1", "title": "...", "price": 99.90 },
    { "sku": "A2", "title": "...", "price": 149.90 },
    ...
  ]
}

Yanıt:

{
  "accepted": 498,
  "rejected": 2,
  "rejections": [
    { "index": 137, "sku": "A138", "code": "validation.failed", "field": "price" }
  ],
  "job_id": "job_xyz"
}

Job durumunu /v1/jobs/{job_id} ile takip et.