Hatalar ve hız sınırları

Her reddedilen Hermetry yönetim REST API isteği, HTTP durum koduyla birlikte bir JSON gövdesidir. Bu sayfa bu gövdenin nasıl okunacağını, hangi sınırların bulunduğunu ve entegrasyonunuzun nasıl tepki vermesi gerektiğini açıklar.

Hata gövdesi

Çoğu hata şu biçimdedir:

{
  "message": "The device limit of this account is reached.",
  "code": "FORBIDDEN",
  "details": { "key": "max_devices", "limit": 43, "current": 43, "adding": 1 }
}

Alan	Anlamı
message	İnsanlar için İngilizce bir cümle. Ayrıştırmayın: değişebilir.
code	Hata türü için sabit bir kod (aşağıdaki tablo)
details	İstemcinin daha fazlasıyla işlem yapabildiği durumlarda bulunur: reason (sabit makine kodu), key (bir plan sınırı), keys, issues

Varyantlar:

Durum	Gövde
Bir alan kuralını ihlal eden gövde veya sorgu	400 { "message": "Validation error", "issues": [{ "path": ["name"], "message": "…" }] }
Bazı rotalar gövdeyi kendileri denetler	400 { "message": "<the problems, joined with commas>" }
Hatalı biçimli JSON	400 { "message": "Malformed request body" }
Beklenmeyen bir sunucu hatası	500 { "message": "Internal server error" } (nedeni bizim tarafımızda kaydedilir, gösterilmez)

Önce duruma, sonra code ve details.reason değerine göre dallanın. Her rota başvurusu kendi nedenlerini listeler.

Durum kodları

Durum	Anlamı	Ne yapılmalı
200, 201	Tamamlandı (201: oluşturuldu)
202	Kabul edildi, hâlâ çalışıyor (bir komut)	Sonucu daha sonra okuyun
400	İstek geçerli değil	İsteği düzeltin; olduğu gibi yeniden denemeyin
401	Geçerli kimlik bilgisi yok: “Invalid or expired API key.”	Anahtarı kontrol edin; yeniden denemeyin
403	Anahtarın veya sahibinin bunu yapma yetkisi yok, anahtara bu adresten izin verilmiyor ya da bir plan sınırına ulaşıldı	Anahtarın izinlerini ve sahibinin rolünü kontrol edin; details.key için planı kontrol edin
404	Bulunamadı ya da sizin tarafınızdan görülemiyor	Kimliği ve anahtarın izinlerini kontrol edin
405	Yöntem burada izinli değil (örneğin istemci özniteliklerine yazma)
409	Çakışma: bir kopya, hâlâ kullanımda olan bir kayıt, eyleme izin vermeyen bir durum ya da başka birinin yaptığı bir değişiklik	Yeniden okuyun, sonra karar verin
412	Kayıt, okuduğunuzdan beri değişti (If-Match)	Yeniden okuyun ve değişikliğinizi yeniden uygulayın
413	Gövde veya dosya çok büyük	Daha az gönderin
415	Yanlış Content-Type (MCP sunucuları)	application/json gönderin
422	İçerik bir iş kuralını ihlal ediyor	İçeriği düzeltin
428	Gerekli ön koşul başlığı eksik (If-Match)	Gönderin
429	Bir hız sınırı	Retry-After saniye bekleyin, sonra yeniden deneyin
500	Tarafımızdaki bir hata	Geri çekilmeyle (backoff) daha sonra yeniden deneyin
503	Geçici olarak kullanılamıyor, örneğin kuruluşunuz taşınıyor: “This workspace is read-only while it is being moved. Please try again later.” (code TENANT_READ_ONLY, Retry-After: 300)	Retry-After sonrasında yeniden deneyin; okuma işlemleri çalışmaya devam eder

Kodlar

code	Tipik durum
VALIDATION_ERROR	400, 413, 422, 428
UNAUTHORIZED	401
FORBIDDEN	403
FEATURE_NOT_AVAILABLE	403: planınız bu özelliği içermiyor
TENANT_SUSPENDED, TENANT_INACTIVE	403: kuruluşunuz etkin değil
TENANT_IP_NOT_ALLOWED	403: kuruluşunuzun IP kuralları bu adresi reddediyor
NOT_FOUND	404
CONFLICT	409, 412
RATE_LIMIT_EXCEEDED	429
INTERNAL_ERROR	500, 503

Plan sınırları

Bir plan sınırı, details.key içinde sınırın adını, details.limit içinde değerini ve details.current içinde mevcut sayınızı taşıyan bir 403‘tür; örneğin bir cihaz oluştururken max_devices. Bkz. Kullanım ve kotalar ve Planlar ve IoT eklentisi.

Hız sınırları

Her API anahtarı çağrısına birkaç sınır uygulanır. Her biri tükendiğinde 429 yanıtı verir.

Sınır	Varsayılan	Kapsam	Mesaj
Adres sınırı	Dakikada 120 istek, aynı anda en fazla 120	Çağıran IP adresi başına	“Too many requests. Please try again later.”
Plan sınırı	Planınız tarafından belirlenir (plan belirlemiyorsa yok)	Kuruluş başına, tüm anahtarlar ve oturum açmış üyeler birlikte	“Your plan’s API rate limit has been reached. Please try again shortly or upgrade your plan.”
Anahtar sınırı	Dakika başına 1.000 çağrı (API anahtarı ayarlarındaki Per-Key Rate Limit)	Anahtar başına	“API key rate limit exceeded. Please slow down.”

Bazı rotalar kendi sınırlarını ekler:

Rota	Sınır
Komutlar	Cihaz başına dakikada 10 (“Too many commands to this device; try again in a minute.”, Retry-After: 60); kuruluş başına dakikada 600 (“Too many requests for your plan. Please upgrade or try again later.”, X-RateLimit-Scope: tenant-plan)
Cihaz ayarı yazmaları	Kuruluş başına dakikada 600
MCP sunucuları	Kimlik bilgisi başına dakikada 120 okuma ve 20 yazma araç çağrısı

429 yanıtındaki başlıklar

Başlık	Anlamı
Retry-After	Bir çağrının yeniden kabul edilmesine kadar geçen saniye
RateLimit-Limit, X-RateLimit-Limit	Dakika başına sınır
RateLimit-Remaining, X-RateLimit-Remaining	Kalan çağrı (0)
RateLimit-Reset	Kovanın yeniden dolmasına kadar geçen saniye

Her 429 yanıtı her başlığı taşımaz. Retry-After yoksa 60 saniye bekleyin.

Adres sınırı sürekli yenilenir: her yarım saniyede bir çağrı geri gelir, bu yüzden saniyede sabit 2 çağrı asla bu sınıra takılmaz. Patlamaları aynı anda göndermek yerine yayın.

Güvenli yeniden deneme

1. Yalnızca 429, 500, 502, 503 ve 504 ile ağ hatalarını yeniden deneyin.
2. Varsa Retry-After kadar bekleyin; yoksa rastgele jitter ile üssel olarak geri çekilin (1, 2, 4, 8 … saniye, en fazla bir dakika).
3. Birkaç denemeden sonra vazgeçin ve son gövdeyi kaydedin.
4. Bir şey oluşturan bir POST‘u (bir cihaz, bir komut) yeniden denemeden önce, ilk çağrının etkili olup olmadığını kontrol edin: önce listeleyin veya okuyun. Komut POST isteğinin bir idempotency anahtarı yoktur.
5. 400, 401, 403, 404 veya 422 yanıtını asla değiştirmeden yeniden denemeyin.

async function call(url, init, tries = 5) {
  for (let i = 0; ; i++) {
    const res = await fetch(url, init);
    if (res.ok || i === tries - 1 || ![429, 500, 502, 503, 504].includes(res.status)) return res;
    const wait = Number(res.headers.get('Retry-After')) || Math.min(60, 2 ** i) + Math.random();
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

İlk karşılaşabileceğiniz hatalar

Gördüğünüz	Olası neden
Her çağrıda 401	Anahtarda yazım hatası, süresi dolmuş veya iptal edilmiş bir anahtar ya da başka bir kuruluşun anahtarı (yoldaki tenantId anahtarınkiyle aynı olmalıdır)
403 “API key does not have the required permission.”	Anahtarda rotanın izni yok. Anahtarın Module permissions ayarını düzenleyin.
403 “You are not permitted to perform this action”	Anahtarda izin var, ama sahibinin artık yok (rol değişti, grup kaldırıldı, erişim politikası)
403 “This API key may not be used from the current IP address.”	Anahtarın IP izin listesi ya da kuruluşun varsayılan listesi
Uygulamada görebildiğiniz bir kayıt için 404	Anahtarın sahibi kayda, anahtarın sahip olmadığı bir izin üzerinden erişiyor ya da kimlik başka bir kuruluşa ait
Yalnızca tek bir sunucudan 429	Adres sınırı: çağrıları yayın ya da daha az, daha büyük sayfalar kullanın