Dokümanlar / Başlarken

Hatalar

Bu sayfada

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

Hatalar

Regvion API'nin hata kodları aşağıdaki tabloda listelenmiştir. Her kod spesifiktir — client kodunuzda error.code string'i üzerinden dallanın, HTTP status üzerinden değil (aynı status farklı anlamlar taşıyabilir: 403 dört, 429 iki ayrı kod döndürür). Tabloda olmayan bir kod görürseniz varsayılan davranışınız retry etmemek ve requestId ile destek talebi açmak olsun.

Zarf

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

error.code — sabit bir kod; tanımlı değerler aşağıdaki tabloda listelenir. Her zaman büyük harf + altı çizili.
error.message — insan okuyabilir açıklama. Client kodunuzda dallanma için kullanmayın.
error.retryAfter — RATE_LIMIT_EXCEEDED ve QUOTA_EXCEEDED için doldurulur; saniye cinsindendir ve Retry-After HTTP başlığıyla aynı değeri taşır. Oran sınırında bu değer saniyeler mertebesindedir; aylık kotada ise gelecek ayın 1'ine (00:00 UTC) kadar olan süredir — yani günler olabilir. Diğer kodlarda null'dur.
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]`)
`SUBSCRIPTION_ENDED`	403	Anahtar geçerli, ama bağlı olduğun kuruluşun Regvion Portal aboneliği sona ermiş	Retry anlamsız — yenilenmesi gereken ANAHTAR değil, ABONELİK. Kuruluş yöneticinle görüş; yenilemenin ardından erişim en geç 5 dakika içinde kendiliğinden döner
`IP_NOT_ALLOWED`	403	İsteğin geldiği IP, müşteri hesabının izinli IP listesinde değil	Retry anlamsız; çıkış IP'ni (NAT/proxy dâhil) admin'ine listeye ekletin — bkz. API Anahtarı
`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	Dakikalık istek limitini aştın	`Retry-After` saniyesi kadar bekle + jitter; üstel geri çekilme
`QUOTA_EXCEEDED`	429	Bu uç nokta için aylık kotanı ya da aylık sohbet token hakkını doldurdun (dakikalık orandan bağımsız)	`Retry-After` gelecek ayın 1'ini (00:00 UTC) gösterir; ay dönmeden retry anlamsız — kota artışı için `[email protected]`
`INTERNAL_ERROR`	500	Sunucuda beklenmedik hata	En fazla 3 kez üstel geri çekilmeyle retry; hâlâ dönüyorsa `requestId` ile destek talebi aç
`NOT_IMPLEMENTED`	501	Uç nokta henüz uygulanmadı (bugün yalnızca `GET /embeddings/{documentId}`)	Retry etme; yol haritası için `[email protected]`

Yeniden deneme kararı

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

429 + RATE_LIMIT_EXCEEDED → retry (backoff + jitter)
429 + QUOTA_EXCEEDED → retry etme — kota ancak ayın 1'inde sıfırlanır; kör retry günlerce boşa döner
500, 502, 503, 504 → retry (en fazla 3)
400, 401, 403 (FORBIDDEN / KEY_EXPIRED / IP_NOT_ALLOWED), 404, 501 → retry etme — aynı parametre, aynı sonuç

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

429 + RATE_LIMIT_EXCEEDED → retry (gövdesi aynı; duplicate risk yok çünkü sunucu henüz işleme almamış)
429 + QUOTA_EXCEEDED → retry etme — aynı gerekçe; kota ay dönmeden açılmaz
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_abcdef0) — tam anahtarı asla paylaşmayın.

Çıktı örneği:

requestId: req_8a3f9e2c4b8d11ef8a3c0242ac120002
         req_9b4fae3d5c9e22fe9b4d0342bc230113
         req_ac50af4e6daf33ff0a5e0442cc340224
endpoint: GET /api/v1/library/semantic
time: ~2026-04-14T09:15:00Z
key prefix: rgv_live_a1b2c3d

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