Hata kataloğu

Tüm API hataları aynı zarfla döner (packages/shared/src/errors.ts):

{
  "error": {
    "code": "HS_VALIDATION_ERROR",
    "message": "İstek doğrulanamadı.",
    "details": { "issues": [{ "path": "contents", "message": "Required" }] },
    "request_id": "req_01…",
    "doc_url": "https://docs.pushizo.com/errors#HS_VALIDATION_ERROR"
  }
}

request_id değeri yanıtın x-request-id başlığıyla aynıdır; destek taleplerinde ve Loglar ekranında aranabilir. Public API istekleri için hata kodu ayrıca x-hs-error-code başlığında döner.

Kod	HTTP	Anlamı	Ne yapmalı
`HS_VALIDATION_ERROR`	400	Gövde/sorgu şemaya uymuyor; `details.issues` alan bazlı listeyi taşır.	İstek şemasını `api/openapi.yaml` ile karşılaştırın.
`HS_BAD_REQUEST`	400	Geçersiz istek (biçim, parametre).	İstek biçimini düzeltin.
`HS_UNAUTHENTICATED`	401	Oturum çerezi veya `Authorization: Bearer hs_live_…` yok/geçersiz.	API anahtarını kontrol edin; dashboard'da yeniden giriş yapın.
`HS_FORBIDDEN`	403	Rol izni, API anahtarı kapsamı, CSRF, org MFA zorunluluğu (`details.reason = mfa_required`) veya IP izin listesi (`ip_not_allowed`).	İlgili izni/kapsamı alın; MFA kurun; IP'nizi listeye ekletin.
`HS_TENANT_MISMATCH`	403	Ayrılmış kod; API üretmez. Başka kiracının kaynağına erişim varlık sızdırmamak için `404 HS_NOT_FOUND` döner (ADR-0011).	—
`HS_NOT_FOUND`	404	Kaynak yok ya da erişiminiz yok (varlık sızdırılmaz).	Kimliği ve kiracı bağlamını kontrol edin.
`HS_CONFLICT`	409	Benzersizlik çakışması (slug, e-posta, alias).	Farklı değer kullanın.
`HS_IDEMPOTENCY_CONFLICT`	409	Aynı `idempotency_key` farklı gövdeyle kullanıldı.	Yeni anahtar üretin ya da aynı gövdeyi gönderin.
`HS_IDEMPOTENCY_IN_PROGRESS`	409	Aynı anahtarlı istek hâlâ işleniyor.	Kısa süre sonra aynı istekle yeniden deneyin.
`HS_NO_RECIPIENTS`	422	Hedef kitle boş (eşleşen aktif abonelik yok).	Hedefi ve kanal yapılandırmasını kontrol edin.
`HS_CHANNEL_NOT_CONFIGURED`	422	Kanal kimlik bilgisi yok veya aktif değil.	Dashboard → Kanallar'dan yapılandırıp doğrulayın.
`HS_CONTENT_INVALID`	422	İçerik kuralları ihlal edildi (uzunluk, URL, Liquid).	İçeriği düzeltin.
`HS_SUBSCRIPTION_INVALID`	422	Abonelik aktif değil.	Cihazın yeniden kayıt olmasını bekleyin.
`HS_UNPROCESSABLE`	422	İstek anlamsal olarak işlenemiyor.	`message` alanına bakın.
`HS_RATE_LIMITED`	429	Hız sınırı aşıldı; `Retry-After` başlığı döner.	Belirtilen süre kadar bekleyip yeniden deneyin (SDK'lar otomatik yapar).
`HS_QUOTA_EXCEEDED`	429	Plan kotası aşıldı.	Planı yükseltin veya kota sıfırlanmasını bekleyin.
`HS_PLAN_FEATURE_REQUIRED`	403	Özellik mevcut planda yok (`details.feature`, `details.plan`).	Planı yükseltin (Faturalama).
`HS_ORG_SUSPENDED`	403	Organizasyon askıya alınmış (`details.reason`); yalnızca faturalama okunabilir.	Faturalamayı düzeltin veya destekle iletişime geçin.
`HS_SUPPORT_READ_ONLY`	403	Platform destek oturumu salt okunurdur.	Değişikliği organizasyon üyesi yapmalı.
`HS_SSO_REQUIRED`	403	Organizasyon "yalnızca SSO" kullanıyor; oturum bu organizasyon için SSO ile açılmamış (`details.org_id`).	Giriş ekranında Kurumsal SSO ile giriş'i kullanın; sahip SSO kurtarma koduyla girebilir.
`HS_INTERNAL`	500	Beklenmeyen hata.	`request_id` ile destek talebi açın.
`HS_NOT_IMPLEMENTED`	501	Özellik bu sürümde yok (segment hedefleme, şablon, saat dilimi teslimatı — Faz 7).	Desteklenen alternatifi kullanın (`message` alanı önerir).
`HS_PROVIDER_UNAVAILABLE`	503	Push sağlayıcısı geçici olarak yanıt vermiyor.	Yeniden deneyin; teslimatlar worker tarafından otomatik yeniden denenir.
`HS_SERVICE_UNAVAILABLE`	503	Servis geçici olarak kullanılamıyor (bakım, bağımlılık).	`/readyz` durumunu kontrol edip yeniden deneyin.

Yeniden deneme kuralları

Sunucu SDK'ları (@pushizo/node, pushizo/pushizo-php) 429 ve 5xx yanıtlarını üstel geri çekilmeyle yeniden dener; 4xx yeniden denenmez.
İstemci SDK'ları çevrimdışı/5xx durumunda işlemleri cihazda kuyruğa alır.
Teslimat tarafında geçici sağlayıcı hataları 30 sn / 2 dk / 10 dk / 30 dk / 2 sa planıyla yeniden denenir; geçersiz token aboneliği invalid yapar (bkz. docs/plan/05).

Hata kataloğu

Yeniden deneme kurallarıBağlantıyı kopyala

Bu sayfada

Yeniden deneme kuralları