Ürün ve API rehberi

Hatalar

Hatalar RFC 9457 problem+json biçiminde döner. Her cevapta bir correlationId bulunur; destek talebinde bu değeri paylaşın.

Durum	Anlamı	Ne yapmalı
`401`	Anahtar eksik veya geçersiz	X-PDFgine-Key başlığını ve anahtarın iptal edilmediğini kontrol edin.
`402`	Kota doldu	Paketi yükseltin veya dönem yenilenene kadar bekleyin.
`404`	Şablon veya belge bulunamadı	Şablon kodunu ve yayınlanmış bir sürümü olduğunu doğrulayın.
`429`	İstek sınırı aşıldı	Retry-After başlığındaki saniye kadar bekleyip tekrar deneyin.

Hız sınırı planla gelir

Üretim uçlarının dakikalık ve saatlik tavanı KİRACI başınadır ve planınızdan gelir; aşağıdaki tablo bunları listeliyor. Tavan anahtar başına değil kiracı başına sayıldığı için ikinci bir API anahtarı açmak tavanı yükseltmez. 429 yanıtı hangi pencereye çarptığınızı X-PDFgine-RateLimit-Scope başlığında söyler: tenant-api, tenant-render-minute ya da tenant-render-hour. Toplu üretimde istek başına bir belge yerine /document-batches ile 100 belgeye kadar tek istek gönderin.

Kota dolduğunda dönen cevap

HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent

{
  "title": "Kullanım kotası aşıldı",
  "status": 402,
  "detail": "Planınızın kullanılabilir sayfa kotası aşıldı.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After ve pencere

Arka arkaya iki tavan uygulanıyor. Birincisi servisi koruyor ve kimlik başına sayıyor: anahtarsız 30, anahtarla 120 istek; pencere 60 saniye. İkincisi planınızdan geliyor ve kiracı başına sayıyor.

Plan	Belge / dakika	Belge / saat
Ücretsiz	15	150
Go	30	300
Pro	60	600
Max	300	3.000

HTTP 429

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute

{
  "title": "Too many requests",
  "status": 429,
  "detail": "The request limit was exceeded. Please try again later.",
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

Pencere sabit, kayan değil: ilk istekle açılıyor, içindeki her istek aynı haktan düşüyor, sonra sayaç sıfırlanıyor. Retry-After o pencerede kalan saniye sayısı — tam o kadar beklemek yeterli, daha erken denemek yalnız bir ret daha harcıyor.

Sık takılınan yerler

Değiştirilmeden tekrarlanan bir 4xx yine düşer. Bunlar "servis meşgul" değil "istek yanlış" der; yalnız 429 ve 5xx yeniden denemeye değer.
429'da yanıt zaten Retry-After taşır. Kendi tahmininizle beklemek ya zaman kaybettirir ya da doğruca bir sonraki redde götürür.
402, gecenin üçünde birini uyandıracak bir arıza değildir. Ay bitmiştir; X-PDFgine-Quota-Remaining'i izleyin ve planı önceden büyütün.
İndirmede 410 kaybolmuş dosya demek değildir. Saklama süresi bitmiştir: belge üretildi, sayıldı ve planınızın takviminde silindi.
Yalnız durum kodunu kütüğe yazmak, destek talebini tahmin oyununa çevirir. Yanına correlationId'yi de yazın; isteği bulan tek değer odur.