Blog · Entegrasyon ve mimari

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.

4 dk okuma

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 durumuerror.codeNe yapmalı?
400invalid_request, invalid_cursor, invalid_code, invalid_queryİsteği düzeltin; aynısını tekrar göndermeyin.
401invalid_api_keyAnahtar yapılandırmasını kontrol edin.
403insufficient_scope, subscription_inactive, forbiddenYetkiyi veya paketi düzeltin.
404dataset_not_found, snapshot_not_foundSürüm ya da snapshot kimliğini kontrol edin.
429rate_limit_exceeded, quota_exceededBekleyin; körlemesine tekrar denemeyin.
503catalog_unavailableGecikmeli 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:

  1. Önce error.code: Bilinen her kod için ayrı bir davranış tanımlayın.
  2. 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'te q 3–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ıttaki meta.nextCursor değ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-Key baş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. Burada error.code belirleyicidir:
  • insufficient_scope: Anahtarın bu özelliğe yetkisi yok. requiredScope alanı eksik yetkiyi gösterir; örneğin doğrulama için addresses:validate.
  • subscription_inactive: Paket aktif değil. subscriptionStatus alanı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, resetAt vb.)
  • Varsa Retry-After değ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.