Hata kodları
Dış API’nin kod kümesi KAPALIDIR: aşağıdaki dokuz kod dışında bir kod yayımlanmaz.
Hata zarfı
Her hata yanıtı aynı zarfı taşır. error makine içindir, message insan içindir ve metni sürümler arasında değişebilir — dallanmanızı error üzerine kurun. details yalnız söyleyecek bir şey varsa gelir.
{
"error": "validation_failed",
"message": "Stok kodu gerekli",
"details": { "field": "code" }
}Aynı kod X-Error-Code yanıt başlığında da durur (gövdeyi okumadan loglayabilirsiniz), ve her yanıt bir X-Request-Id taşır. 500 yanıtlarında bu değer details.request_id alanında da gelir — destek kaydında paylaşacağınız tek değer odur.
Kod kümesi
Bu liste bir projeksiyondur: iç katalog çok daha geniştir (duplicate_vkn, taslak_zaten_gonderildi, …) ve o kodlar iç tablo ve akış adları taşıdığı için dışarıya verilmez. Çakışma ve durum hataları dışarıda conflict ile invalid_state’e indirgenir. Kümeye yeni bir kod eklemek bir sözleşme değişikliğidir ve değişiklik günlüğüne yazılır.
| Kod | HTTP | Anlamı | Ne yapmalı |
|---|---|---|---|
validation_failed | 400 | İstek gövdesi ya da sorgu parametresi doğrulamadan geçemedi. | İsteği tekrar denemeyin; `details.field` hangi alanın reddedildiğini söyler, onu düzeltin. |
unauthorized | 401 | Anahtar bulunamadı, pasif, süresi dolmuş ya da imza/zaman damgası doğrulanamadı — dördü de AYNI yanıtı alır. | Kanonik dizeyi test vektörüne karşı doğrulayın ve sunucu saatinizin ±5 dakika içinde olduğundan emin olun. |
forbidden | 403 | Anahtar geçerli ama bu operasyonun istediği kapsamı taşımıyor. | Eksik kapsam kodu yanıta YAZILMAZ; anahtarın kapsamlarını panelden genişletin. |
not_found | 404 | Kaynak yok ya da başka bir firmaya ait. Mesaj kaynağın türünü söyler, id’sini değil. | Tekrar denemeyin; id’yi ve firmayı doğrulayın. |
conflict | 409 | Kaydın bugünkü durumu isteği kabul etmiyor (örn. zaten gönderilmiş bir taslağı yeniden göndermek). | Kaydı geri okuyup durumuna göre karar verin; kör tekrar aynı yanıtı verir. |
invalid_state | 422 | İstek biçimsel olarak doğru ama iş kuralı bu geçişe izin vermiyor. | Tekrar denemeyin; `message` hangi kuralın engellediğini söyler. |
idempotency_key_reuse | 422 | Aynı `Idempotency-Key` BAŞKA bir istek için kullanılmış. | Her mantıksal işlem için yeni bir anahtar üretin (örn. UUID). |
rate_limited | 429 | Anahtarın dakikalık tavanı aşıldı. | `Retry-After` başlığındaki saniye kadar bekleyip tekrar deneyin — kör retry kotayı hızlandırarak tüketir. |
internal_error | 500 | Sunucu tarafında beklenmeyen hata. | Üstel geri çekilmeyle tekrar deneyin; destek kaydında `details.request_id` değerini paylaşın. |
401 neden sebebini söylemiyor
Anahtarın bulunamaması, pasif olması, süresinin dolması ve imzanın yanlış olması aynı yanıtı alır. Ayrımı yayımlamak, anahtar deneyen birine hangi adımda olduğunu öğretirdi. Kurulumunuzu ayırt etmek için test vektörünü kullanın: vektör tutuyorsa sorun imzada değildir.