# Limitler ve hatalar

> Hız limitleri, bütçe korumaları, X-RateLimit başlıkları ve fix satırlı hata kataloğu. Her hata ne yapacağınızı söyler.

## Hız limitleri

| Yüzey | Limit | Kova |
|---|---|---|
| İşletme API `api/v1` | saniyede 60, günde 10.000 | anahtar başına |
| Platform API `platform/v1` | saniyede 30, günde 50.000 | anahtar başına |
| Anahtarsız dokümanlar | dakikada 10 | IP başına |

Kovalar sunduğunuz anahtara göredir: başka bir partnerin yoğunluğu sizi asla yavaşlatmaz.

Kalan kotanız her yanıtın `X-RateLimit-Limit`, `X-RateLimit-Remaining` ve `X-RateLimit-Reset` başlıklarında gelir. HTTP durum koduna göre dallanın: **429** gelirse bekleyip yeniden deneyin. `Retry-After` başlığı başarılı yanıtlarda da görünebilir, tek başına yavaşlama sinyali değildir.

## Platform bütçeleri

Yazma uç noktaları iki ek korumadan geçer:

- Yazma başına en çok **1.000** birim büyüklük: daha büyüğü `422` döner, bölerek gönderin.
- Günde toplam **100.000** birim: aşımı `429 budget_exceeded` döner ve gece UTC sıfırlanır.

Bu sizin de sigortanızdır: sonsuz döngüye giren bir kod sınırsız bakiye basamaz. Limit işinize dar geliyorsa [biz@sadakio.com](mailto:biz@sadakio.com) ile artırılmasını isteyin.

## Hata biçimi

Her hata aynı zarfla gelir ve `fix` alanı ne YAPACAĞINIZI söyler:

```json
{"error": {"code": "not_found",
           "message": "No such guest in this business.",
           "fix": "Use a guest id returned by POST .../guests."}}
```

## Hata kataloğu

| Kod | HTTP | Anlamı | Yapılacak |
|---|---|---|---|
| `unauthorized` | 401 | Anahtar yok, bilinmiyor, iptal veya askıda | Anahtarı kontrol edin, gerekirse yeni anahtar alın |
| `insufficient_scope` | 403 | Anahtarda gereken kapsam yok | `write` kapsamlı anahtar oluşturun |
| `not_found` | 404 | Sizin kiracılığınızda böyle bir kayıt yok | Kendi listelerinizden dönen id kullanın |
| `validation_failed` | 422 | Gövde doğrulamadan geçmedi | `fix` satırındaki alanı düzeltin |
| `budget_exceeded` | 429 | Günlük yazma bütçesi doldu | Gece sıfırlanmasını bekleyin veya artırım isteyin |
| `rate_limited` | 429 | Hız limiti | `Retry-After` kadar bekleyip yeniden deneyin |

Önemli: yabancı bir kaynağa erişim de `not_found` döner, `forbidden` değil. API bir varlık kahini değildir.