Bir API çağrısının başarısız olması, her zaman route’un hata verdiği anlamına gelmez. İstek dış erişimde, HTTP eşleştirmesinde veya şema kontrolünde durabilir. Önce hangi hedefi çağırdığınızı ve hangi katmanın yanıt verdiğini belirleyin.
İnceleme sırası
- Hedefi belirleyin. Sonuç Mock mu, Running project mi, yayımlanan adres mi? Mock sonucu gerçek route’u; Running project sonucu gateway kimlik doğrulamasını kanıtlamaz.
- Adres ve yöntemi kaydedin. Ortam origin’i, proje kimliği, server taban yolu ve operation yolunu kontrol edin. Copy operation address ile alınan şablondaki path değişkenlerini gerçek değerle doldurun.
- Etkin sürümü kontrol edin. API Save, route Saved, ardından gerekli Run/Reload tamamlandı mı? Deployment için doğru dosyalar commit edilip Build edildi mi? Serving hangi hedefi gösteriyor?
- HTTP sonucunu okuyun. Durum kodu, content type, gövde ve varsa Request contract checks birlikte değerlendirilmelidir.
- İlgili yerde düzeltin. Sözleşme hatası API design’da; iş davranışı route’ta; dış erişim hatası API access ve ortam kaynaklarında çözülür.
Daha istek göndermeden hata alıyorsanız
| Belirti | Anlamı | Sonraki işlem |
|---|---|---|
| Save kullanılamıyor | Read-only, belge hatası veya uygulanmamış alan düzenlemesi olabilir | Hata listesini inceleyin; JSON alt alanında Apply/Discard işlemini tamamlayın. |
| Form editing unavailable | Source, görsel düzenleme için gerekli yapıda değil | Geçerli JSON, desteklenen OpenAPI sürümü ve info tanımını kontrol edin. |
Add a route consuming direct:… | Operation’ın iş girişi yok | Route ID’yi değil, from.uri içindeki Direct adını eşleştirin. |
Multiple routes consume direct:… | Aynı operation için birden fazla giriş var | Bir Direct consumer bırakın; ortak mantığı başka bir Direct route’a taşıyın. |
Consume direct:… without endpoint options | Operation’ın Direct girişinde endpoint seçeneği var; API çağrısı bu girişe ulaşmaz | from.uri değerini tam olarak direct:<operationId> bırakın; ? sonrasındaki seçenekleri ve parameters alanını kaldırın. |
| An OpenAPI project cannot also declare REST consumers | HTTP işlemleri iki ayrı yerde tanımlanmış | İşlemleri openapi.json içine alın ve Direct route’ları kullanın. |
| Unsupported request validation at… | Request schema’sında çalıştırılmayan bir özellik var | Gösterilen konumu destek tablosuyla karşılaştırın. |
| Çakışan operation veya yol | Aynı yöntem/yol, eşdeğer parametreli yol veya yinelenen ID var | Örneğin /orders/{id} ile /orders/{orderId} aynı yöntem için iki ayrı işlem değildir. |
| Çalışan runtime yok | Running project isteğinin gideceği geliştirme runtime’ı hazır değil | Run ve runtime durumunu kontrol edin; gerektiğinde Refresh runtime status kullanın. |
HTTP sonucuna göre ilerleyin
| Sonuç | İlk bakılacak yer | Kontrol |
|---|---|---|
| Bağlantı kurulamıyor / TLS hatası | Ortam adresi ve transport | Host, port, ağ erişimi, HTTPS listener ve sertifika; schema’yı değiştirmek çözmez. |
| 400 | Yanıt gövdesi ve Request contract checks | JSON sözdizimi, required, type, minimum, enum ve diğer bildirilen kurallar. |
| 401 | Kimlik doğrulama | Eksik/geçersiz credential, token süresi, issuer, audience ve imza doğrulaması. |
| 403 | İzin politikası | Tanınan kimliğin izinleri, scope’lar ve ortam policy’sinin eşleşmesi. |
| 404 / 405 | Adres, yöntem, yayınlanan işlemler | Yanlış proje ön eki veya path, yanlış HTTP yöntemi, kapalı erişim; yanıta göre iş kaydının bulunamaması da olabilir. |
| 406 | Accept / Response content type | İstenen yanıt biçimi sözleşmede var mı? Try it içinde No preference ile tekrar karşılaştırın. |
| 415 | Content-Type / Request content type | Gönderilen gövde biçimi operation’da bildiriliyor mu? |
| 422 veya uygulamanızın başka iş hata kodu | İş route’u ve hata gövdesi | Sözleşme geçse de stok, müşteri limiti veya başka iş koşulu reddedebilir. |
| 500 / 502 / 503 / 504 | Hatanın geldiği katman ve runtime | İş istisnası, bağlı sistem, hazır endpoint, gateway policy/Secret veya bekleme sorunu. |
Gateway ve iş uygulaması aynı kodu farklı nedenlerle döndürebilir. Yalnızca sayıdan kesin neden çıkarmayın; yanıtı, Publication → Detail bilgisini ve ilgili çalışma kayıtlarını birlikte okuyun. Özellikle 404, dış erişim kapanmasıyla route’un “sipariş bulunamadı” yanıtını tek başına ayırt etmez.
Şema hatasının gövdesini okuyun
Lunex request doğrulama hatası, application/problem+json biçiminde güvenli bir açıklama döndürür. Örneğin minimum değeri 1 olan miktara 0 gönderildiğinde:
{
"type": "about:blank",
"title": "Request does not satisfy the OpenAPI contract.",
"status": 400,
"errors": [
{
"location": "body /quantity",
"rule": "minimum",
"message": "Must be greater than or equal to the minimum."
}
]
}location girdinin yerini, rule ihlal edilen kuralı, message açıklamayı verir. Bir query veya header hatasında konum ilgili parametreyi belirtir. Eksik alan veya fazladan alan hatasında konum body / gibi üst nesne olabilir; o nesnenin Required ve ek alan kurallarını inceleyin. Yanıt, reddedilen credential veya veri değerlerini size geri yazmak zorunda değildir.
Open schema setting varsa ilgili tanıma gidin. Gerçekten kural mı yanlış, yoksa istemci mi eksik veri gönderiyor, bunu belirleyin. Kuralı değiştirdiyseniz Save → Reload sonrasında aynı çağrıyı tekrarlayın. 406 ve 415 gibi taşıma katmanı yanıtlarında gövde boş olabilir; her hata için bu JSON yapısını beklemeyin.
Runtime testi başarılı, dış çağrı başarısız
Bu durumda önce API access inceleyin. Exposure uygulanmış mı, seçilen HTTP/HTTPS ortamda hazırlanmış mı, credential veya JWT policy doğru namespace’te mi, Publication hazır mı? Dış adresi kopyalayıp aynı istekle deneyin.
Lunex kullanıcı oturumunuzun açık olması dış API için API key veya token gönderildiği anlamına gelmez. Basic/API key Secret adını credential değeri yerine kullanmayın. JWT’de client_id ile audience aynı kavram değildir; beklenen issuer, audience ve izinleri güvenlik rehberindeki sırayla karşılaştırın.
Eski davranış geliyor
Mock seçiliyse sözleşmenin response örneğini görürsünüz. Running project seçiliyse kaydedilip yüklenmiş geliştirme kaynakları kullanılır. Dış URL’de ise Serving ile gösterilen hedef kullanılır.
API kaydını ve route autosave sonucunu kontrol edin. Reload’un tamamlandığını doğrulayın. Yeni bir bağımlılık eklediyseniz runtime’ı yeniden başlatın. Deployment için çalışma alanına Save yapmak yeterli değildir; gerekli dosyaların build edilen commit’te bulunması gerekir.
İstek uzun sürüyor veya sonuç alınamıyor
Önce runtime’ın ve çağırdığı sistemin durumuna bakın. Cancel, tarayıcının beklemesini durdurur; daha önce başlayan kayıt, ödeme veya mesaj gönderme işini geri almaz. Sonuç belirsizse aynı POST isteğini tekrar göndermeden önce iş kaydını araştırın. Tekrarlı çağrılardan korunma davranışı gerekiyorsa bunu iş akışınızda tasarlayın.
Running project testinde istek gövdesi ve yanıt tamponu ayrı ayrı 1 MiB ile sınırlıdır. Test request body exceeds 1 MiB. mesajında girdiyi küçültün; büyük gerçek çağrıları uygun HTTP istemcisinde sınayın. Bu test aracının sınırı, her dış servis çağrısının aynı sınıra sahip olduğu anlamına gelmez.
Destek kaydı için bilgileri hazırlayın
Ortam/proje, operation ID, yöntem/yol, deneme zamanı, kullanılan hedef, HTTP kodu, güvenli hata gövdesi ve son uyguladığınız Save/Reload/Build adımını kaydedin. Route’a ulaşmış işlemler için mevcut Message Monitor kayıtlarını ilişkilendirin. Gateway’de veya request kontrolünde durdurulan istek için iş route’u kaydı bulunmasını beklemeyin.
Paylaşacağınız örnekte token, parola, API key ve gerçek müşteri verisini gösterim değerleriyle değiştirin; hatayı üreten veri türünü ve yapısını koruyun. Tekrar üretmek için sipariş örneğindeki doğru/yanlış girdi karşılaştırması kullanılabilir.