Dokümanlar / Başlarken

Hatalar

Bu sayfada

Hatalar
Zarf
Hata kodları
Yeniden deneme kararı
Destek talebinde ne paylaş

Hatalar

Regvion API'nin yedi hata kodu vardır. Her kod spesifiktir — client kodunuzda error.code string'i üzerinden dallanın, HTTP status üzerinden değil (aynı status farklı anlamlar taşıyabilir).

Zarf

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Document not found.",
    "retryAfter": null
  },
  "meta": {
    "requestId": "req_8a3f9e2c4b8d11ef8a3c0242ac120002"
  }
}

error.code — enum, aşağıdaki tablodan biri. Her zaman büyük harf + altı çizili.
error.message — insan okuyabilir açıklama. Client kodunuzda dallanma için kullanmayın.
error.retryAfter — yalnızca RATE_LIMIT_EXCEEDED için doldurulur; saniye cinsinden.
meta.requestId — destek talebi için kritik.

Hata kodları

Kod	HTTP	Ne zaman	Ne yapmalı
`UNAUTHORIZED`	401	`X-API-Key` eksik, boş veya sunucunun tanımadığı bir hash	Başlık adını ve anahtarı kontrol et; başlık case-sensitive değildir, değer case-sensitive'dir
`KEY_EXPIRED`	403	Anahtarın son kullanma tarihi geçmiş ve grace period de dolmuş	Admin'den yeni anahtar iste; bu noktada retry çalışmaz
`FORBIDDEN`	403	Anahtar geçerli ama tier bu uç noktaya izin vermiyor	Tier yükseltme için satışa yaz (`[email protected]`)
`NOT_FOUND`	404	Kaynak yok veya boru hattı tamamlanmamış (yayınlanmamış)	Retry anlamsız; ID'yi kontrol et
`VALIDATION_ERROR`	400	Gövde şemaya uymuyor veya query alanı geçersiz	`error.message` alanındaki açıklamayı oku, gövdeyi düzelt
`RATE_LIMIT_EXCEEDED`	429	Saatlik kotanı aştın	`Retry-After` saniyesi kadar bekle + jitter; üstel geri çekilme
`INTERNAL_ERROR`	500	Sunucuda beklenmedik hata	En fazla 3 kez üstel geri çekilmeyle retry; hâlâ dönüyorsa `requestId` ile destek talebi aç

Yeniden deneme kararı

Idempotent çağrılar (GET, DELETE, PUT):

429 → retry (backoff + jitter)
500, 502, 503, 504 → retry (en fazla 3)
400, 401, 403, 404 → retry etme — aynı parametre, aynı sonuç

Non-idempotent çağrılar (POST oluşturma):

429 → retry (gövdesi aynı; duplicate risk yok çünkü sunucu henüz işleme almamış)
500 → tehlikeli. Sunucu isteği aldı mı bilmiyoruz — duplicate yaratabiliriz. Mümkünse önce GET ile state kontrolü, sonra retry.

Destek talebinde ne paylaş

Birden çok istek için en az üç requestId.
Hata dönen tam endpoint path'i.
İstek zamanı (yaklaşık, ISO 8601).
Anahtarınızın yalnızca ilk 16 karakteri (rgv_live_abcdef01...) — tam anahtarı asla paylaşmayın.

Çıktı örneği:

requestId: req_8a3f9e2c4b8d11ef8a3c0242ac120002
         req_9b4fae3d5c9e22fe9b4d0342bc230113
         req_ac50af4e6daf33ff0a5e0442cc340224
endpoint: POST /api/v1/search/semantic
time: ~2026-04-14T09:15:00Z
key prefix: rgv_live_a1b2c3d4

Bu formatı destek e-postasına kopyalayın — tipik yanıt süresi 1 iş günü altıdır.