06 · Hata Kodları

Tüm hata yanıtları tek tipte:

{
  "error": {
    "code": "invalid_signature",
    "message": "Request signature could not be verified.",
    "request_id": "req_01HM..."
  }
}

request_id her yanıtta X-Request-Id header'ında da gelir; sorun açarken bu ID'yi paylaşın.

Tam liste

HTTP	`code`	Anlam
400	`invalid_request`	Query/body malformed, bilinmeyen param, limit dışı
401	`missing_signature_headers`	4 zorunlu header'dan biri eksik
401	`invalid_key`	Key bilinmiyor / REVOKED / EXPIRED / partner SUSPENDED
401	`invalid_signature`	HMAC eşleşmiyor (secret yanlış / canonical yanlış)
401	`expired_timestamp`	`\|now - timestamp\| > 5dk`
401	`replay_detected`	Nonce daha önce kullanıldı (10dk pencerede)
403	`ip_not_allowed`	Kaynak IP key'in allowlist'inde değil
403	`scope_required`	Endpoint için key'in scope'u yetersiz
403	`tls_required`	HTTP üzerinden istek geldi (sadece HTTPS)
404	`not_found`	Kaynak yok veya partner'a açık değil (ID enumeration koruması)
429	`rate_limited`	Rate limit aşıldı. `Retry-After` header'ı bekleme süresini verir
500	`internal_error`	Beklenmedik sunucu hatası. `request_id` ile destek talebi açın
501	`not_implemented`	Reserved endpoint (örn. webhooks/test)

404 vs 403 farkı

Bazı API'larda kaynağa erişim yoksa 403, kaynak yoksa 404 döner. Biz her iki durumda da 404 dönüyoruz — bu kasıtlı bir güvenlik kararı. 403 dönmek "burada bir şey var ama izniniz yok" demektir; saldırgan ID enumeration ile gerçek ID'leri keşfedebilir. 404 ile partner A, partner B'nin raporlarının var olduğunu bile öğrenemez.

Saat senkronu sorunları

expired_timestamp aldıysanız:

# Sunucunuzun saatini ekspertiz.app ile kıyaslayın
curl -sI https://api.ekspertiz.app/api/v1/partner/health | grep -i date
date -u

Fark 5 dk'dan fazlaysa NTP'yi düzeltin.

Retry stratejisi

Hata	Retry?	Nasıl
`429 rate_limited`	✅	`Retry-After`'a uy
`500 internal_error`	✅	Exponential backoff (1s, 2s, 4s, max 30s)
`502/503/504`	✅	Exponential backoff
`4xx` (yukarıdakiler hariç)	❌	Düzeltmeden retry etmeyin
`replay_detected`	✅ (yeni nonce ile)	Aynı nonce'u tekrar göndermeyin

Sonraki: 07 · Sandbox vs Production.