API Hata Kodları: error.code ile Sağlam Entegrasyon
API hata kodlarını error.code üzerinden ele alın: 400 hataları, 401 ve 403 farkı, kullanıcıya doğru mesaj göstermek ve destek için doğru kayıt tutmak.
Bir entegrasyonun sağlam olup olmadığı, istekler başarısız olduğunda anlaşılır. API hata kodlarını doğru okuyan bir uygulama kullanıcıya anlamlı bir mesaj gösterir. Sorunu otomatik olarak çözebiliyorsa çözer, çözemiyorsa destek ekibine gerekli bilgiyi kaybetmeden iletir. Bu yazıda API Türkiye'nin hata gövdesini temel alarak bir hata katmanının nasıl kurulacağını adım adım ele alıyoruz. Konular sırasıyla şunlar: koda göre karar vermek, 400 yanıtlarını ayıklamak, 401 ile 403'ü ayırmak ve destek talebi için iz bırakmak.
Hata gövdesinin yapısı
Başarılı /v1 yanıtları data alanını, bazı uçlarda ek olarak meta alanını döner. Hata yanıtlarında ise gövde bir error nesnesi içerir:
{ "error": { "code": "invalid_api_key", "message": "Geçerli bir X-API-Key başlığı zorunludur." } }
error.code makinenin okuyacağı sabit bir tanımlayıcıdır. error.message ise insanın okuyacağı açıklamadır. Hata türüne göre gövdede requiredScope, subscriptionStatus, period, limit, resetAt gibi ek alanlar da bulunabilir.
Durumu hızlıca görmek için anahtarsız bir istek gönderebilirsiniz:
curl -i "https://api.apiturkiye.com/v1/provinces"
Bu istek 401 durum koduyla ve invalid_api_key koduyla döner. Rehberde tanımlı başlıca kodlar şunlardır:
| HTTP durumu | error.code | Ne yapmalı? |
|---|---|---|
400 | invalid_request, invalid_cursor, invalid_code, invalid_query | İsteği düzeltin; aynısını tekrar göndermeyin. |
401 | invalid_api_key | Anahtar yapılandırmasını kontrol edin. |
403 | insufficient_scope, subscription_inactive, forbidden | Yetkiyi veya paketi düzeltin. |
404 | dataset_not_found, snapshot_not_found | Sürüm ya da snapshot kimliğini kontrol edin. |
429 | rate_limit_exceeded, quota_exceeded | Bekleyin; körlemesine tekrar denemeyin. |
503 | catalog_unavailable | Gecikmeli olarak tekrar deneyin. |
API hata kodları neden mesaja göre değil, koda göre ele alınır?
message metni kullanıcıya yardımcı olmak için yazılır. Bu yüzden ifadesi zamanla iyileştirilebilir, ayrıntı eklenebilir ya da tarih biçimi değişebilir. if (message.includes("anahtar")) gibi bir kontrol, metindeki ilk küçük düzenlemede sessizce bozulur. HTTP durum kodları ise yalnız kaba bir sınıflandırma sunar. Örneğin 403 hem eksik yetki hem de pasif paket anlamına gelebilir.
Doğru yaklaşım iki katmanlıdır:
- Önce
error.code: Bilinen her kod için ayrı bir davranış tanımlayın. - Sonra HTTP durumu: Tanımadığınız bir kod gelirse durum sınıfına göre güvenli bir varsayılana düşün. 4xx hatalarında tekrar denemeyin. 5xx hatalarında sınırlı ve gecikmeli tekrar deneyin.
message alanını karar mantığına sokmayın. Bu alan günlük kayıtlarında ve geliştirici araçlarında işinize yarar.
400 yanıtları: isteği düzeltmek
400, sorunun gönderdiğiniz istekte olduğunu söyler. Bu yüzden aynı isteği tekrar göndermek sonucu değiştirmez. Kodlar, sorunun nerede olduğunu daraltır:
invalid_query: Arama sorgusu geçersiz. Autocomplete'teq3–100 karakter olmalıdır ve normalize edilmiş hâli de en az 3 karakter içermelidir.invalid_cursor: Sayfalama imleci geçersiz. Cursor değerini üretmeye ya da değiştirmeye çalışmayın; yalnız yanıttakimeta.nextCursordeğerini aynen gönderin.invalid_code: Yoldaki il, ilçe, mahalle veya sokak kodu geçersiz.invalid_request: Gövde ya da parametreler hatalı. Örneğin doğrulama ucunda zorunlu bir alan eksiktir ya da bir alan uzunluk sınırını aşmıştır.
details alanı hakkında: Rehber, 400 yanıtları için alan bazlı hataları listeleyen bir details alanı tanımlamaz. Belgelenen sözleşme error.code, error.message ve hata türüne özgü ek alanlardan oluşur. Bu nedenle form doğrulamanızı böyle bir alana bağlamayın. error nesnesindeki ek alanları olduğu gibi günlüğe yazın; ancak karar mantığını yalnız belgelenmiş alanlara dayandırın. Alan bazlı geri bildirimi istemci tarafında kendiniz üretin. Zorunlu alanları ve uzunluk sınırlarını formda kontrol ederseniz 400 yanıtlarının çoğu hiç oluşmaz.
Önemli bir ayrım daha var. POST /v1/addresses/validate ucunda geçerli gövdeli ama katalogda eşleşmeyen bir adres 400 döndürmez. Bu durumda yanıt 200 olur ve gövdede data.valid: false, data.failedAt ve data.suggestions bulunur. 400, yalnız hatalı veya eksik JSON gövdesi anlamına gelir. Bu iki durumu aynı mesajla karşılamayın.
401 ve 403 farkı
İki durum benzer görünse de farklı sorunlara işaret eder:
401 invalid_api_key: API sizi tanımıyor.X-API-Keybaşlığı eksik, hatalı, süresi dolmuş ya da iptal edilmiş olabilir. Çoğu zaman bir yapılandırma hatasıdır: ortam değişkeni yüklenmemiştir, başlık adı yanlış yazılmıştır ya da test ve canlı anahtarları karışmıştır. Anahtarın güvenli saklanması için API anahtarı rehberine bakabilirsiniz.403: API sizi tanıyor, ancak bu işlem için izin vermiyor. Buradaerror.codebelirleyicidir:insufficient_scope: Anahtarın bu özelliğe yetkisi yok.requiredScopealanı eksik yetkiyi gösterir; örneğin doğrulama içinaddresses:validate.subscription_inactive: Paket aktif değil.subscriptionStatusalanına bakın.forbidden: Temel adres okuma yetkisi yok.
İki durumda da otomatik tekrar denemesi yapmayın. Anahtar, yetki ya da paket düzeltilmeden sonuç değişmez. Bu hatalar son kullanıcının çözebileceği sorunlar değildir. Kullanıcıya kısa ve genel bir mesaj gösterin, ekibinizi ise uyarı mekanizmasıyla bilgilendirin.
Hata katmanını tek noktada kurmak
Aşağıdaki JavaScript yardımcısı sunucu tarafında çalışır. Her isteğe yerel bir kimlik atar, hata gövdesini güvenli biçimde ayrıştırır ve tipli bir hata fırlatır. Anahtar tarayıcıya hiç gönderilmez.
import { randomUUID } from "node:crypto";
export class ApiError extends Error {
constructor({ status, code, message, extra, localRequestId }) {
super(message);
this.status = status;
this.code = code;
this.extra = extra;
this.localRequestId = localRequestId;
}
}
export async function apiRequest(path, { method = "GET", body } = {}) {
const localRequestId = randomUUID();
const res = await fetch(`https://api.apiturkiye.com${path}`, {
method,
headers: {
"X-API-Key": process.env.APITURKIYE_KEY,
...(body ? { "Content-Type": "application/json" } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.ok) return res.json();
let payload = null;
try { payload = await res.json(); } catch { /* JSON olmayan gövde */ }
const { code = "unknown_error", message = `HTTP ${res.status}`, ...extra } =
payload?.error ?? {};
console.error(JSON.stringify({
localRequestId,
at: new Date().toISOString(),
method,
path: path.split("?")[0], // sorgu metnini günlüğe yazmayın
status: res.status,
code,
extra,
retryAfter: res.headers.get("Retry-After"),
}));
throw new ApiError({ status: res.status, code, message, extra, localRequestId });
}
Kullanıcıya gösterilecek metni ayrı bir fonksiyonda üretin. Böylece API mesajları doğrudan arayüze sızmaz:
export function toUserMessage(err) {
switch (err.code) {
case "invalid_query":
return "Aramak için en az 3 karakter yazın.";
case "invalid_request":
return "Adres bilgilerinde eksik veya hatalı alan var. Lütfen kontrol edin.";
case "rate_limit_exceeded":
return "Şu an çok fazla istek var. Lütfen biraz sonra tekrar deneyin.";
case "catalog_unavailable":
return "Adres hizmetine şu an ulaşılamıyor. Lütfen biraz sonra tekrar deneyin.";
case "invalid_api_key":
case "insufficient_scope":
case "subscription_inactive":
case "forbidden":
case "quota_exceeded":
return `Adres hizmeti geçici olarak kullanılamıyor. Destek kodu: ${err.localRequestId}`;
default:
return err.status >= 500
? "Beklenmeyen bir sunucu hatası oluştu. Lütfen tekrar deneyin."
: `İşlem tamamlanamadı. Destek kodu: ${err.localRequestId}`;
}
}
Aynı yapının Python karşılığı aşağıdadır. Doğrulama örneği, 400 ile valid: false ayrımını da gösterir:
import os, uuid, logging, requests
from datetime import datetime, timezone
BASE = "https://api.apiturkiye.com"
class ApiError(Exception):
def __init__(self, status, code, message, extra, local_request_id):
super().__init__(message)
self.status, self.code, self.extra = status, code, extra
self.local_request_id = local_request_id
def api_request(method, path, json_body=None):
local_id = str(uuid.uuid4())
res = requests.request(
method, BASE + path,
headers={"X-API-Key": os.environ["APITURKIYE_KEY"]},
json=json_body, timeout=10,
)
if res.ok:
return res.json()
try:
err = dict(res.json().get("error", {}))
except ValueError:
err = {}
code = err.pop("code", "unknown_error")
message = err.pop("message", f"HTTP {res.status_code}")
logging.error("api_error id=%s at=%s %s %s status=%s code=%s extra=%s",
local_id, datetime.now(timezone.utc).isoformat(),
method, path.split("?")[0], res.status_code, code, err)
raise ApiError(res.status_code, code, message, err, local_id)
try:
body = api_request("POST", "/v1/addresses/validate", {
"province": "İstanbul", "district": "Kadıköy",
"neighborhood": "Caferağa Mahallesi", "street": "Moda Caddesi",
"doorNumber": "12",
})
result = body["data"]
if not result["valid"]:
print("Eşleşmedi:", result["failedAt"], result.get("suggestions", []))
except ApiError as e:
if e.code == "insufficient_scope":
print("Eksik yetki:", e.extra.get("requiredScope"))
else:
raise
Tekrar deneme politikası da koda göre belirlenmelidir. rate_limit_exceeded geldiğinde Retry-After başlığındaki süre kadar bekleyin. quota_exceeded geldiğinde resetAt zamanına kadar aynı çağrıyı tekrarlamayın. Bu iki durumun ayrıntılarını 429 hatası rehberinde bulabilirsiniz. catalog_unavailable için artan aralıklarla birkaç deneme yapın ve servis durumu sayfasını kontrol edin. Ayrıca şunu unutmayın: 429 dışındaki hata yanıtlarının kotadan düşülmeyeceğini varsaymayın. Hatalı bir isteği döngü içinde tekrarlamak hem gereksiz yük oluşturur hem de kotanızı tüketebilir.
requestId ile destek talebi
Rehber, hata gövdesinde ya da yanıt başlıklarında bir requestId alanı tanımlamaz. Bu nedenle destek sürecini böyle bir alana dayandırmak yerine kendi izinizi tutun. Yukarıdaki örneklerde her isteğe atanan localRequestId bu işi görür. Kullanıcı ekranında "Destek kodu" olarak gösterilen değer, günlükteki kayıtla doğrudan eşleşir. Kullanıcı bu kodu ilettiğinde ilgili kaydı saniyeler içinde bulursunuz.
Destek talebi açarken şu bilgileri derleyin:
- İsteğin UTC zaman damgası
- HTTP yöntemi ve uç yolu (sorgu metni olmadan)
- HTTP durumu ve
error.code - Ek alanlar (
requiredScope,subscriptionStatus,resetAtvb.) - Varsa
Retry-Afterdeğeri
Asla paylaşmayın: API anahtarınızı ve snapshot indirme bağlantılarındaki token değerini. Kullanıcıların yazdığı adres metinlerini de günlüklere ve destek taleplerine eklemeden önce, kişisel veri açısından değerlendirin. Bu konuda hukuki bir soru varsa bir uzmana danışmanız gerekir. Derlediğiniz bilgileri [email protected] adresine iletebilirsiniz.
Sonraki adım
Hata katmanını kurduktan sonra her kodu bilinçli olarak tetikleyerek test edin: anahtarsız istek, kısa arama sorgusu, eksik doğrulama gövdesi. Tüm kodların ve ek alanların güncel listesine API dokümantasyonundan ulaşabilirsiniz. Henüz bir anahtarınız yoksa ücretsiz kayıt olarak Core paketiyle denemeye başlayabilirsiniz.