Hata Kodları

Tüm yüzeylerdeki (Veri API, yazma ucu, hook'lar, aksiyon, webhook) dokümante hata mesajları tek yerde. Veri API hataları HTTP 200 + { success:false, message } zarfında döner (auth hatası 401 hariç); her kodun anlamı ve çözümü aşağıda.

Hata zarfı

// Veri API hata zarfı
{ "success": false, "message": "<kod>" }

// Başarı
{ "success": true, "data": … }

Veri API (GET /plugin-api/*)

message	HTTP	Anlam / çözüm
plugin.scope.denied	200	Ucun istediği scope onaylı değil → manifest'e ekle, tenant yeniden onaylasın.
unauthorized	401	Geçersiz/eksik install `apiKey` → token exchange'teki anahtarı kullan.
plugin.rateLimited	429	Rate limit aşıldı → backoff + retry. Limitler (DEV 5/dk, write 20/dk).
plugin.<kaynak>.notFound	200	Kayıt yok (`packets`/`tables`/`products`/`categories`/`customers`) → id'yi doğrula.
plugin.<kaynak>.missingParams	200	Zorunlu parametre eksik/yanlış adlı (örn. `packets/get` → `packetId`, `customers/get` → `customerId`).

Yazma — POST /plugin-api/packets/create

message	Anlam / çözüm
joi doğrulama mesajı	Geçersiz gövde (eksik/yanlış alan) → gövde şeması.
Product not found: <id>	cart'taki bir ürün yok — TÜM ürünler var olmalı (yarım sipariş yazılmaz).
Paid amount is greater than total…	`payments` toplamı sipariş tutarını aşıyor.
Duplicate request already in progress	Aynı `idempotencyKey` ile eşzamanlı 2. istek.
Server not found	Geçersiz tenant.
callbackUrl must be under the same domain…	`callbackUrl` manifest `webhookUrl`'üyle aynı registered domain değil (400).
callbackUrl rejected: <sebep>	Güvenlik kontrolünden geçemedi (private IP / DNS) (400).

Hook'lar (gate çağrısı)

message	Anlam / çözüm
plugin.hook.notOwner	Paket sizin değil (yalnız packet.status.update'te — sahiplik damgası eşleşmedi).
plugin.hook.targetNotFound	Hedef (paket/masa) bulunamadı.
plugin.hook.missingTransition	Geçiş bağlamı eksik/geçersiz (panel hatası).
plugin.hook.notRegistered	Manifest'inizde bu hook yok.
plugin.hook.gateRequired	Gate yanıtı bekleniyor — iframe gate'i `resolve`/`close` ile sonuçlandırmadınız.
plugin.hook.inactive	Kurulum pasif (kill-switch / billing / connect).
plugin.scope.denied	İlgili `hooks:<action>` scope'u onaylı değil.

Aksiyon / senkron timeout

message	Anlam / çözüm
plugin.action.timeout	Senkron aksiyon/hook cevabı süresinde gelmedi (`timeoutMs`). Hook'ta `failMode` uygulanır.
plugin.rateLimited	Senkron çağrı kovası aşıldı (Limitler).

Genel kurallar: ortak hata kodları her uçta plugin.scope.denied ve plugin.<kaynak>.notFound; auth her zaman 401, rate limit 429. İlgili: Veri API · Hook'lar · Limitler · İmza (401).