Marketplace API Hataları

Marketplace hata yanıtları Content-Type: application/problem+json ve RFC 9457 Problem Details biçimini kullanır.

code, type, title ve status sürümlü kanonik registry'den gelir. detail, güvenli ve yerelleştirilmiş yönlendirmedir. Bir route kararlı bir uygulama nedeni taşıyorsa reasonCode, HTTP kategorisi olan code alanını değiştirmeden bu nedeni taşır. Sağlayıcı mesajları ve kanıt referansları public yanıta bilerek dahil edilmez. Varsa requestId değerini loglayın; bunu idempotency anahtarı olarak kullanmayın.

İstemci yanıt gövdesini yalnız bir kez tüketmelidir. Media type application/problem+json ise legacy {success,error,code} alanlarını aramak yerine Problem Details doğrulanmalı; kullanıcı metni detail, iş akışı ayrımı reasonCode (yoksa code) ve HTTP ayrımı gerçek yanıt status'undan alınmalıdır. Geçersiz Problem Details gövdesini ikinci kez JSON okumaya çalışmayın; doğrulanamayan yanıt olarak kapalı tutun.

revision_conflict, aggregate'in okumanızdan sonra değiştiğini belirtir. Güncel kaynağı alın, komutu bu revizyondan tekrar oluşturun ve yeni bir idempotency anahtarıyla gönderin.

too_early (HTTP 425), aynı idempotent komutun hâlâ işlendiğini belirtir. Retry-After süresine uyun; ardından komut receipt'ini sorgulayın veya aynı idempotency anahtarıyla yeniden deneyin. İlk komutun sonucu belirsizken yeni bir anahtar üretmeyin.

rate_limited için Retry-After süresini ve jitter kullanın. unavailable yanıtını yalnız idempotent işlemlerde tekrar deneyin. Bir yazmada internal_error alırsanız sonuç belirsiz olabileceğinden önce kaynak veya komut receipt durumunu uzlaştırın.

Tam kod registry'si ve uyumluluk kuralları için sürümlü sözleşmeye bakın.

OpenAPI 3.1 registry sözleşmesi, public problem-type sorgulama endpoint'ini tanımlar ve kanonik JSON Schema'ya bağlanır. Belgenin kapsamı yalnız problem registry'sidir; tüm Marketplace iş route'larının istek ve başarılı yanıt payload'larının OpenAPI olarak yayımlandığı iddia edilmez.

Kanonik JSON Schema ve AsyncAPI 3.1 event sözleşmesi, byte-identical generated mirror'lardan yayımlanır. Public artifact'ın eksik veya farklı olması Marketplace PR kapısını başarısız kılar.

Tüm Marketplace route JSON yanıtları tek serializer'dan geçer. HTTP hata yanıtı veya legacy success: false/ok: false sonucu Problem Details'a dönüştürülür; yanlışlıkla hata statüsü verilmeyen failure, HTTP 500 ve internal_error ile fail closed olur.