Hata Kodları

Tüm yüzeylerdeki (Veri API, yazma ucu, hook'lar, aksiyon, webhook) dokümante hata mesajları tek yerde. Veri API hataları artık REST-uyumlu HTTP status döner (not-found 404, doğrulama 400, scope/sahiplik 403, çakışma 409, rate limit 429, auth 401); gövde { success:false, message } korunur (message = makine-okur kod). Her kodun anlamı ve çözümü aşağıda.

Hata zarfı

// Hata — REST-uyumlu HTTP status + zarf (message makine-okur koddur)
HTTP 404
{ "success": false, "message": "plugin.packets.notFound" }

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

SDK/istemci: 4xx'i hata olarak işle; message'a göre dallan (i18n anahtarı değil, sabit koddur). Eski davranış (her şey HTTP 200) kaldırıldı — gövde uyumlu kaldı.

Veri API (GET /plugin-api/*)

message	HTTP	Anlam / çözüm
plugin.scope.denied	403	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ı → `Retry-After`'a uy. Limitler (DEV 5/dk, write 20/dk).
plugin.<kaynak>.notFound	404	Kayıt yok (`packets`/`tables`/`products`/`categories`/`customers`) → id'yi doğrula.
plugin.<kaynak>.missingParams	400	Zorunlu parametre eksik/yanlış adlı (örn. `packets/get` → `packetId`, `customers/get` → `customerId`).

Yazma — POST /plugin-api/* (packets/tables/katalog)

message	HTTP	Anlam / çözüm
joi doğrulama mesajı	400	Geçersiz gövde (eksik/yanlış alan) → gövde şeması.
Product not found: <id>	400	cart'taki bir ürün yok — TÜM ürünler var olmalı (yarım sipariş yazılmaz).
unknown_payment_method	400	Ödeme satırı `id`'si tenant'ın yöntemi değil → önce payment-methods/list.
no_payment_methods_configured	400	Tenant'ta hiç ödeme yöntemi tanımlı değil.
Paid (X) exceeds total (Y).	400	`payments` toplamı sipariş tutarını aşıyor.
categoryNotEmpty	409	Boş olmayan kategori silinemez (önce ürünleri taşı/sil).
Duplicate request already in progress	409	Aynı `idempotencyKey` ile eşzamanlı 2. istek.
plugin.<kaynak>.notOwner	403	Yalnız kendi oluşturduğun katalog kaydını düzenler/silersin (sahiplik).
Table/Server not found	404	Masa kapanmış (tables yalnız açık masaları tutar) / geçersiz tenant.
callbackUrl must be under the same domain…	400	`callbackUrl` manifest `webhookUrl`'üyle aynı registered domain değil.
callbackUrl rejected: <sebep>	400	Güvenlik kontrolünden geçemedi (private IP / DNS).

Masa açma (tables/create) durum kodları: 400 — tableId salon planında yok ya da masa pasif (masa layout'tan gelmeli; uydurulamaz) · 409 — masa zaten açık (mevcut adisyona dokunulmaz → kalem eklemek için tables/update-orders) ya da aynı idempotencyKey ile eşzamanlı istek. İş hatasında (400/404/409) idempotency anahtarı serbest bırakılır: isteği düzeltip aynı anahtarla tekrar denenebilir.

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).

Eklentiler-arası yetenekler (capability)

Tam kod plugin.<errorPrefix>.<suffix>; <errorPrefix> = capability id'nin İLK segmenti (plugin.messaging / plugin.notify / plugin.invoice). Ör. notify.staff için plugin.notify.noProvider (plugin.notify.staff.* DEĞİL).

message (suffix)	HTTP	Anlam / çözüm
…noProvider	424	Tenant sağlayıcı bağlamamış — önkoşul eksik → özelliği gizle, retry etme.
…providerUnavailable	503	Sağlayıcı inaktif/askıda/breaker-open/ulaşılamaz → aynı key ile sonra dene.
…timeout	504	Sağlayıcı ≈10s içinde yanıtlamadı → AYNI idempotencyKey ile retry (belirsiz sonuç).
…providerChanged	409	Belirsiz sonuç + tenant sağlayıcı değişimi → çift-işlem koruması; retry engellendi, manuel uzlaştır.
…duplicateInProgress · …idempotencyKeyReused · …selfTarget	409	Sırasıyla: eşzamanlı çift çağrı · aynı key farklı içerik · tüketici=sağlayıcı.
…suspended · …consumerBlocked	403	Eklenti kill-switch'te · tenant tüketiciyi panelden engellemiş.
…idempotencyKeyRequired · …rawPiiForbidden · …invalidPayload	400	Key eksik · to'da ham PII · payload doğrulaması başarısız.
plugin.capability.notFound	404	Bilinmeyen capability (jenerik `/capabilities/{cap}/*` ucunda).

Ayrıntı + sağlayıcı rehberi: Yetenekler — Genel Bakış.

HTTP eşlemesi (Veri API): not-found 404 · doğrulama/eksik param 400 · scope/sahiplik 403 · çakışma 409 · rate limit 429 · auth 401 · yetenek önkoşulu 424 · sağlayıcı 503/504. message her zaman makine-okur koddur. İlgili: Veri API · Hook'lar · Yetenekler · Limitler · İmza (401).