{"id":112,"date":"2026-10-28T06:39:00","date_gmt":"2026-10-28T06:39:00","guid":{"rendered":"https:\/\/www.akifsen.com.tr\/blog\/?p=112"},"modified":"2026-10-28T06:39:00","modified_gmt":"2026-10-28T06:39:00","slug":"api-error-response-problem-details","status":"publish","type":"post","link":"https:\/\/www.akifsen.com.tr\/blog\/2026\/10\/28\/api-error-response-problem-details\/","title":{"rendered":"Hata Cevaplar\u0131n\u0131 Tasarlamak: RFC 9457 Problem Details"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">Bir API&#8217;nin ba\u015far\u0131l\u0131 cevaplar\u0131 genellikle \u00f6zenle tasarlan\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Hata cevaplar\u0131 ise zamanla birikir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Bir endpoint \u015funu d\u00f6nd\u00fcr\u00fcr:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{ \"error\": \"User not found\" }<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Bir di\u011feri:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{ \"message\": \"Validation failed\", \"code\": 1003 }<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">\u00dc\u00e7\u00fcnc\u00fcs\u00fc HTML bir hata sayfas\u0131 d\u00f6ner, \u00e7\u00fcnk\u00fc exception framework seviyesine kadar \u00e7\u0131km\u0131\u015ft\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Client geli\u015ftiricisi her biri i\u00e7in ayr\u0131 parse kodu yazar.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Problem Details<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">RFC 9457, HTTP API&#8217;lerinde hata cevaplar\u0131 i\u00e7in ortak bir format tan\u0131ml\u0131yor. Daha \u00f6nceki RFC 7807&#8217;nin g\u00fcncellenmi\u015f hali.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>HTTP\/1.1 422 Unprocessable Content\nContent-Type: application\/problem+json\n\n{\n  \"type\": \"https:\/\/api.example.com\/problems\/insufficient-funds\",\n  \"title\": \"Yetersiz bakiye\",\n  \"status\": 422,\n  \"detail\": \"Hesap bakiyesi 30 TL, i\u015flem tutar\u0131 50 TL.\",\n  \"instance\": \"\/transfers\/8812\"\n}<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>type:<\/strong> Hatan\u0131n t\u00fcr\u00fcn\u00fc tan\u0131mlayan bir URI. Client&#8217;\u0131n programatik olarak kontrol edece\u011fi alan budur.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>title:<\/strong> Hata t\u00fcr\u00fcn\u00fcn insan taraf\u0131ndan okunabilir k\u0131sa a\u00e7\u0131klamas\u0131. Ayn\u0131 type i\u00e7in hep ayn\u0131d\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>detail:<\/strong> Bu \u00f6zel duruma ait a\u00e7\u0131klama.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>instance:<\/strong> Hatan\u0131n olu\u015ftu\u011fu kayna\u011fa veya iste\u011fe referans.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Bunlar\u0131n yan\u0131na hataya \u00f6zel alanlar eklenebilir. Yukar\u0131daki \u00f6rnekte <code>balance<\/code> ve <code>amount<\/code> alanlar\u0131 eklemek, client&#8217;\u0131n kullan\u0131c\u0131ya daha iyi bir mesaj g\u00f6stermesini sa\u011flar.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Spring 6 ile <code>ProblemDetail<\/code> s\u0131n\u0131f\u0131 framework&#8217;e yerle\u015fik geldi. <code>spring.mvc.problemdetails.enabled=true<\/code> ile framework&#8217;\u00fcn kendi hatalar\u0131 da bu formatta d\u00f6nmeye ba\u015fl\u0131yor.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Mesaja g\u00f6re karar verilmemeli<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Client&#8217;lar\u0131n hata mesaj\u0131 metnine g\u00f6re karar vermesi s\u0131k g\u00f6r\u00fclen bir hata:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>if (error.message.includes(\"not found\")) ...<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Mesaj de\u011fi\u015ftirildi\u011finde veya \u00e7evrildi\u011finde client k\u0131r\u0131l\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Programatik kararlar i\u00e7in sabit bir tan\u0131mlay\u0131c\u0131 gerekir. Problem Details&#8217;te bu <code>type<\/code> alan\u0131d\u0131r. Sabit, belgelenmi\u015f ve de\u011fi\u015fmeyen bir de\u011fer.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Do\u011frulama hatalar\u0131<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Form do\u011frulama hatalar\u0131nda birden fazla alan ayn\u0131 anda hatal\u0131 olabilir. Bunlar\u0131 tek bir mesajda birle\u015ftirmek client&#8217;\u0131n i\u015fini zorla\u015ft\u0131r\u0131r:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>\"detail\": \"email ge\u00e7ersiz, password \u00e7ok k\u0131sa\"<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Alan baz\u0131nda bir liste daha kullan\u0131\u015fl\u0131d\u0131r:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>\"errors\": [\n  { \"field\": \"email\", \"code\": \"invalid_format\" },\n  { \"field\": \"password\", \"code\": \"too_short\", \"min\": 8 }\n]<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Client her hatay\u0131 ilgili form alan\u0131n\u0131n alt\u0131nda g\u00f6sterebilir. <code>code<\/code> alan\u0131 sayesinde mesajlar\u0131 kendi dilinde \u00fcretebilir.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Status code do\u011fru se\u00e7ilmeli<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Her hatay\u0131 <code>400<\/code> veya <code>500<\/code> ile d\u00f6nmek, client&#8217;\u0131n en temel ayr\u0131m\u0131 yapmas\u0131n\u0131 engeller.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Kabaca:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>400<\/code>: \u0130stek bozuk, parse edilemiyor.<\/li>\n\n\n<li><code>401<\/code>: Kimlik do\u011frulanmam\u0131\u015f.<\/li>\n\n\n<li><code>403<\/code>: Kimlik do\u011fru ama yetki yok.<\/li>\n\n\n<li><code>404<\/code>: Kaynak yok.<\/li>\n\n\n<li><code>409<\/code>: Mevcut durumla \u00e7ak\u0131\u015fma.<\/li>\n\n\n<li><code>422<\/code>: \u0130stek anla\u015f\u0131l\u0131r ama i\u015f kural\u0131na uymuyor.<\/li>\n\n\n<li><code>429<\/code>: \u00c7ok fazla istek.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><code>4xx<\/code> client&#8217;\u0131n d\u00fczeltmesi gereken bir \u015feyi, <code>5xx<\/code> sunucu taraf\u0131ndaki bir problemi anlat\u0131r. Retry mant\u0131klar\u0131 da genellikle bu ayr\u0131ma g\u00f6re kurulur. <code>5xx<\/code> tekrar denenebilir, <code>4xx<\/code> genellikle denenmemelidir.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">\u0130\u00e7 detaylar\u0131 s\u0131zd\u0131rmamak<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Stack trace, SQL hata mesaj\u0131 veya s\u0131n\u0131f isimleri hata cevab\u0131na girmemeli. Hem g\u00fcvenlik riski olu\u015fturur hem de client i\u00e7in anlams\u0131zd\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Bunun yerine bir trace ID d\u00f6nd\u00fcrmek, destek ekibinin sunucu loglar\u0131nda ilgili kayd\u0131 bulmas\u0131n\u0131 sa\u011flar:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>\"traceId\": \"4bf92f3577b34da6\"<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Hata cevaplar\u0131 bir API&#8217;nin en \u00e7ok okunan ama en az tasarlanan k\u0131sm\u0131.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Client geli\u015ftiricileri dok\u00fcmantasyonda ba\u015far\u0131l\u0131 ak\u0131\u015f\u0131 bir kez okur. Hata cevaplar\u0131yla ise her g\u00fcn u\u011fra\u015f\u0131r.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Her endpoint farkl\u0131 bir hata format\u0131 d\u00f6nd\u00fcr\u00fcyorsa client&#8217;lar her biri i\u00e7in ayr\u0131 kod yazar. Problem Details standard\u0131, hata kodlar\u0131 ve do\u011frulama hatalar\u0131n\u0131n tasar\u0131m\u0131.<\/p>\n","protected":false},"author":1,"featured_media":111,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[9],"tags":[],"class_list":["post-112","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-api-tasarimi"],"_links":{"self":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/112","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/comments?post=112"}],"version-history":[{"count":1,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/112\/revisions"}],"predecessor-version":[{"id":196,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/112\/revisions\/196"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/media\/111"}],"wp:attachment":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/media?parent=112"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/categories?post=112"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/tags?post=112"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}