Hata kodları
Merkez API'sinden gelen her hata aynı biçimi paylaşır. API'ye karşı geliştirme yapıyorsanız kodlayacağınız sözleşme budur.
Zarf
{
"code": "NOT_FOUND",
"statusCode": 404,
"path": "/api/v1/projects/018f3a1e-…",
"timestamp": "2026-08-20T09:15:00.000Z"
}
| Alan | Anlamı |
|---|---|
code | Sabit ve makine tarafından okunabilir. Buna göre dallanın. |
statusCode | HTTP durumu, gövdede tekrarlanır. |
path | Hata veren istek yolu. |
timestamp | Hatanın zamanı, ISO-8601. |
message | Bazen bulunur. Geliştiriciye yöneliktir, yerelleştirilmez, sabit değildir. |
code, API sözleşmesinin parçasıdır ve habersiz değişmez. message bir
geliştirici yardımıdır — ifadesi her an değişebilir ve hiçbir zaman çevrilmez.
Ondan arayüz metni üretmek bozulur.Bir NOT_FOUND ayrıca neyin bulunamadığını söyleyen entity ve id taşır.
Kodlar
| Kod | HTTP | Anlamı | Yapılacak |
|---|---|---|---|
VALIDATION_ERROR | 400, 422 | Gövde veya sorgu hatalı ya da uç noktanın kabul etmediği bir alan taşıyor. | İsteği API referansı ile karşılaştırın. Bilinmeyen alanlar yok sayılmaz, reddedilir. |
UNAUTHENTICATED | 401 | Belirteç eksik, bozuk veya süresi dolmuş. | Belirteci yenileyin ya da yeniden giriş yapın. |
UNAUTHORIZED | 403 | Kimlik doğrulandı ama izin yok. | Üyenin rolünü ve aktif kiracıyı kontrol edin. |
NOT_FOUND | 404 | Çağıranın kiracısında böyle bir kayıt yok. | Kimliği — ve kiracıyı — kontrol edin. Aşağıya bakın. |
CONFLICT | 409 | Değişiklik mevcut bir kayıtla çakışıyor. | Genelde yinelenen bir tanımlayıcı veya kısa ad. |
SIGFOX_LIVE_DISABLED | 403 | Sağlayıcıya canlı yazma burada kapalı. | Plan uç noktalarını kullanın ya da bir operatörden açmasını isteyin. |
INTERNAL_ERROR | 500 | Beklenmedik bir hata. | Yeniden deneyin; sürüyorsa bildirmeye değer bir hatadır. |
Kiracı dışı okumalar neden 404
Başka bir kiracıya ait bir kaydı istemek 403 değil 404 döndürür.
Bu bilinçlidir. 403, kimliğin var olduğunu doğrular ve bu bilgiyi kiracı sınırının dışına sızdırır. Bir kiracının dışından bakıldığında kayıtları, hiç oluşturulmamış kayıtlardan ayırt edilemez.
Pratik sonucu: var olduğundan emin olduğunuz bir kimlikte 404 almak genelde
yanlış kiracı demektir, yanlış kimlik değil. Gönderdiğiniz x-tenant-id
değerini kontrol edin.
Bilinmeyen alanlar reddedilir
API, tanımadığı özellikleri taşıyan istek gövdelerini sessizce yok saymak yerine reddeder.
Bu, aksi hâlde sessizce başarısız olacak yazım hatalarını yakalar — deviceId
yerine deviceID göndermek, kaybolan bir alan değil, anında gördüğünüz bir
hatadır.
Doğru görünen bir istekte VALIDATION_ERROR alıyorsanız, her şeyden önce fazladan
veya yanlış yazılmış bir özellik olup olmadığına bakın.
Uç noktalardaki hatalar
Uç noktalar farklı davranır, çünkü bir Merkez belirteciyle doğrulanmazlar:
| Durum | Anlamı |
|---|---|
| 201 | Kabul edildi ve döndürülecek bir şey var — örneğin bir downlink. |
| 204 | Kabul edildi, söylenecek bir şey yok. Olağan başarı. |
| 401 | Kaynağın adaptörü yükü reddetti — yanlış gizli anahtar, doğrulanamayan imza veya eksik bir zorunlu başlık. Bir giriş sorunu değildir. |
| 404 | Böyle bir entegrasyon, anahtar veya kısa ad yok. Genelde göndericinin hâlâ kullandığı, döndürülmüş bir anahtar. |