> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perquery.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hatalar ve limitler

> Perquery API'sinin hata yanıtlarını, hız limitini ve sayfalamasını okuyun.

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.

```json theme={null}
{
  "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.

> [!TIP]
>
> 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](#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.

```json theme={null}
{
  "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.

**1. İstekleri durdurun**

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

**2. Bekleyin**

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

**3. İsteği yeniden gönderin**

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

> [!TIP]
>
> 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ş](https://docs.perquery.ai/tr/api/introduction.md) 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.

```bash theme={null}
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.

## İlgili sayfalar

* [API'ye giriş](https://docs.perquery.ai/tr/api/introduction.md)
* [Kimlik doğrulama](https://docs.perquery.ai/tr/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.