Hatalar ve limitler

Bu sayfa Perquery API’sinin hataları nasıl bildirdiğini, bir anahtarın kaç istek gönderebileceğini ve uzun listeleri sayfa sayfa nasıl okuyacağınızı anlatır.

Hata biçimi

API her hatayı application/problem+json medya türünde bir problem ayrıntıları nesnesi (RFC 9457) olarak gönderir.

{
  "type": "https://perquery.ai/problems/not-found",
  "title": "The resource was not found.",
  "status": 404,
  "detail": "Site not found.",
  "instance": "/v1/sites/0b6f1c3e-5d1a-4c3b-9a7e-2f4d8c1b6a90",
  "correlation_id": "4f9c2d7e8a1b4c6d9e0f1a2b3c4d5e6f"
}

Alan	Açıklama
`type`	Hata slug’ı ile biten bir URL.
`title`	Hata türünün kısa açıklaması.
`status`	HTTP durum kodu.
`detail`	Bu hatanın açıklaması.
`instance`	İsteğin yolu.
`correlation_id`	İsteğin kimliği.

Bazı hatalar başka alanlar da ekler. Örneğin missing-entitlement hatası add_on_code alanını ekler.

Kodunuzda type alanının sonundaki slug’ı kullanın. title ve detail metinleri değişebilir. API bu metinleri İngilizce gönderir.

Hata slug’ları

Durum	Slug	Neden
`400`	`bad-request`	İstek geçerli değil.
`401`	`unauthorized`	Anahtar yok, doğru değil, iptal edildi veya süresi doldu.
`403`	`forbidden`	İstek `GET` dışında bir yöntem kullanıyor veya API anahtarları bu endpoint’i kullanamaz.
`403`	`missing-entitlement`	Organizasyonunuzda API erişimi add-on’u yok.
`403`	`permission-denied`	Anahtarı oluşturan üyenin rolleri bu isteğe izin vermiyor.
`403`	`membership-suspended`	Anahtarı oluşturan üyenin üyeliği askıya alındı.
`403`	`organization-suspended`	Organizasyonunuz askıya alındı.
`404`	`not-found`	Kaynak yok veya yol doğru değil.
`406`	`not-acceptable`	`Accept` başlığı JSON dışında bir biçim istiyor.
`422`	`validation-failed`	Bir sorgu parametresi geçerli değil.
`429`	`usage-limit`	Anahtar çok fazla istek gönderdi. Hız limiti bölümünü okuyun.
`500`	`internal-error`	Sunucuda beklenmeyen bir hata oluştu.

Doğrulama hataları

Bir sorgu parametresi geçerli değilse API, validation-failed slug’ı ile 422 yanıtı verir. errors listesi her parametreyi ve sorunu belirtir.

{
  "type": "https://perquery.ai/problems/validation-failed",
  "title": "The request body failed validation.",
  "status": 422,
  "detail": "The request content could not be processed.",
  "instance": "/v1/sites/0b6f1c3e-5d1a-4c3b-9a7e-2f4d8c1b6a90/technical/findings",
  "errors": [
    {
      "field": "page_size",
      "reason": "Ensure this value is less than or equal to 100.",
      "code": "max_value"
    }
  ]
}

Alan	Açıklama
`field`	Parametrenin adı.
`reason`	Sorunun açıklaması.
`code`	Sorun için kısa bir kod, örneğin `max_value` veya `invalid`.

İstek kimliği

Her yanıtta bir X-Request-Id başlığı vardır. Bu başlığın değeri, hata yanıtındaki correlation_id değeriyle aynıdır. Bir istek hakkında destek ekibine yazdığınızda bu kimliği verin. Kendi X-Request-Id başlığınızı da gönderebilirsiniz. Değer 1 ile 128 arasında harf, rakam, ., _ veya - karakteri içerebilir. API bu durumda sizin değerinizi kullanır.

Hız limiti

Her API anahtarı 60 saniyelik bir pencerede 600 istek gönderebilir. Pencere, anahtarın ilk isteğiyle başlar. Bir anahtar daha fazla istek gönderirse API, usage-limit slug’ı ile 429 yanıtı verir. Yanıtta Retry-After başlığı yoktur.

İstekleri durdurun

429 yanıtı aldığınızda bu anahtarla istek göndermeyi durdurun.

Bekleyin

60 saniye bekleyin. Pencere bundan sonra yeniden başlar.

İsteği yeniden gönderin

İsteği yeniden gönderin. Yine 429 yanıtı alırsanız sonraki denemeden önce daha uzun bekleyin.

Limitin altında kalmak için isteklerinizi zamana yayın. Bir endpoint destekliyorsa ETag ve If-None-Match başlıklarını kullanın. API’ye giriş sayfasını okuyun.

Sayfalama

Uzun listeler döndüren endpoint’ler listeyi sayfa sayfa gönderir. Bu endpoint’ler iki sorgu parametresi kabul eder:

Parametre	Açıklama
`page`	Sayfa numarası. İlk sayfa `1`’dir. Varsayılan değer `1`’dir.
`page_size`	Bir sayfadaki öğe sayısı. Varsayılan değer `50`’dir. Endpoints referansı her endpoint’in en yüksek değerini gösterir.

Yanıt, sayfanın öğelerini ve şu alanları içerir:

Alan	Açıklama
`total`	Tüm sayfalardaki öğe sayısı.
`page`	Bu sayfanın numarası.
`page_size`	Bir sayfadaki öğe sayısı.
`total_pages`	Sayfa sayısı. Sayfalama yapan endpoint’lerin çoğu bu alanı gönderir.

Listenin adı endpoint’e göre değişir, örneğin rows, findings veya pages. Endpoints referansı her endpoint için bu adı gösterir.

curl "https://perquery.ai/api/v1/sites/{site_uuid}/technical/findings?page=2&page_size=100" \
  -H "Authorization: ApiKey $PERQUERY_API_KEY"

Tüm öğeleri okumak için page=1 ile başlayın. page değeri total_pages değerine eşit olana kadar page değerini birer artırın. total_pages göndermeyen bir endpoint’te, okuduğunuz öğelerin sayısı total değerine ulaşınca durun.

​Hata biçimi

​Hata slug’ları

​Doğrulama hataları

​İstek kimliği

​Hız limiti

​Sayfalama

​İlgili sayfalar

Hata biçimi

Hata slug’ları

Doğrulama hataları

İstek kimliği

Hız limiti

Sayfalama

İlgili sayfalar