Hata Kodları

Bu sayfa, SeoAuthor API'yi kullanırken karşılaşabileceğiniz tüm hata kodlarını ve çözüm yollarını açıklamaktadır.

🚨 HTTP Status Kodları

2xx - Başarılı İşlemler

Kod	Durum	Açıklama
200	OK	İşlem başarıyla tamamlandı
201	Created	Kaynak başarıyla oluşturuldu

4xx - İstemci Hataları

400 Bad Request

Açıklama: Gönderilen istek geçersiz veya hatalı parametreler içeriyor.

Yaygın Sebepler:

Zorunlu alanların eksik olması
Geçersiz veri formatı
Geçersiz JSON yapısı
Karakter limiti aşımı

Örnek Yanıt:

{
  "error": "ValidationError",
  "message": "Baslik alanı zorunludur ve boş bırakılamaz",
  "statusCode": 400,
  "details": {
    "field": "baslik",
    "code": "REQUIRED",
    "value": ""
  }
}

Çözüm:

Tüm zorunlu alanları doldurun
Veri formatlarını kontrol edin
API dokümantasyonunu tekrar inceleyin

401 Unauthorized

Açıklama: Kimlik doğrulama başarısız veya token geçersiz.

Yaygın Sebepler:

Authorization header eksik
Geçersiz access token
Süresi dolmuş token
Yanlış token formatı

Örnek Yanıt:

{
  "error": "Unauthorized",
  "message": "Geçersiz veya süresi dolmuş token",
  "statusCode": 401,
  "code": "TOKEN_EXPIRED"
}

Çözüm:

// Token yenileme
try {
  await refreshToken();
  // İsteği tekrar dene
} catch (error) {
  // Kullanıcıyı giriş sayfasına yönlendir
  redirectToLogin();
}

403 Forbidden

Açıklama: İsteğiniz geçerli ancak bu işlemi yapmaya yetkiniz yok.

Yaygın Sebepler:

Yetersiz hesap bakiyesi
Erişim izni olmayan kaynak
Hesap kısıtlaması

Örnek Yanıt:

{
  "error": "Forbidden",
  "message": "Yetersiz bakiye. Makale oluşturmak için minimum 25 TL gerekli.",
  "statusCode": 403,
  "code": "INSUFFICIENT_BALANCE",
  "requiredBalance": 25.0,
  "currentBalance": 10.5
}

Çözüm:

// Bakiye kontrolü
const balance = await getCurrentBalance();
if (balance.amount < requiredAmount) {
  alert("Yetersiz bakiye. Lütfen hesabınıza bakiye yükleyin.");
}

404 Not Found

Açıklama: İstenen kaynak bulunamadı.

Yaygın Sebepler:

Yanlış endpoint URL'i
Var olmayan kaynak ID'si
Silinmiş içerik

Örnek Yanıt:

{
  "error": "NotFound",
  "message": "Makale bulunamadı",
  "statusCode": 404,
  "code": "ARTICLE_NOT_FOUND",
  "requestedId": 12345
}

409 Conflict

Açıklama: İstek mevcut kaynak durumuyla çakışıyor.

Yaygın Sebepler:

Aynı başlıkla makale zaten var
Eşzamanlı işlem çakışması

Örnek Yanıt:

{
  "error": "Conflict",
  "message": "Bu başlıkla bir makale zaten mevcut",
  "statusCode": 409,
  "code": "DUPLICATE_TITLE",
  "existingArticleId": 98765
}

422 Unprocessable Entity

Açıklama: İstek formatı doğru ancak iş mantığı kurallarına aykırı.

Yaygın Sebepler:

Konu limiti aşımı
Geçersiz parametre kombinasyonu

Örnek Yanıt:

{
  "error": "UnprocessableEntity",
  "message": "Konu limit aşımı",
  "statusCode": 422,
  "code": "TOPIC_LIMIT_EXCEEDED",
  "currentCount": 15,
  "maxLimit": 10
}

429 Too Many Requests

Açıklama: Rate limit aşıldı, çok fazla istek yapıldı.

Örnek Yanıt:

{
  "error": "TooManyRequests",
  "message": "Rate limit aşıldı. 60 saniye sonra tekrar deneyin.",
  "statusCode": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60,
  "limit": 100,
  "remaining": 0,
  "resetTime": 1692789660
}

Çözüm:

// Exponential backoff with retry
async function apiCallWithRetry(apiCall, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiCall();
    } catch (error) {
      if (error.status === 429) {
        const waitTime = error.retryAfter || Math.pow(2, i) * 1000;
        console.log(`Rate limit hit, waiting ${waitTime}ms`);
        await new Promise((resolve) => setTimeout(resolve, waitTime));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

5xx - Sunucu Hataları

500 Internal Server Error

Açıklama: Sunucu tarafında beklenmeyen bir hata oluştu.

Örnek Yanıt:

{
  "error": "InternalServerError",
  "message": "Sunucu hatası oluştu",
  "statusCode": 500,
  "code": "INTERNAL_ERROR",
  "requestId": "req_123456789"
}

Çözüm:

İsteği birkaç dakika sonra tekrar deneyin
Sorun devam ederse teknik destek ile iletişime geçin

502 Bad Gateway

Açıklama: Gateway hatası, upstream servis yanıt vermiyor.

503 Service Unavailable

Açıklama: Servis geçici olarak kullanılamıyor.

Örnek Yanıt:

{
  "error": "ServiceUnavailable",
  "message": "Sistem bakımda. Tahmini süre: 30 dakika",
  "statusCode": 503,
  "code": "MAINTENANCE_MODE",
  "estimatedDuration": 1800
}

🔍 Özel Hata Kodları

Authentication Hataları

Kod	Açıklama	Çözüm
`INVALID_CREDENTIALS`	Yanlış email/şifre	Bilgilerinizi kontrol edin
`TOKEN_EXPIRED`	Token süresi dolmuş	Token yenileyin
`TOKEN_INVALID`	Token formatı hatalı	Yeni token alın
`REFRESH_TOKEN_EXPIRED`	Refresh token süresi dolmuş	Yeniden giriş yapın

Makale Hataları

Kod	Açıklama	Çözüm
`TITLE_TOO_LONG`	Başlık çok uzun	255 karakter sınırına uyun
`TITLE_TOO_SHORT`	Başlık çok kısa	En az 10 karakter girin
`INVALID_TONE`	Geçersiz yazım tonu	1-5 arası değer kullanın
`INVALID_SIZE`	Geçersiz makale boyutu	1-4 arası değer kullanın
`DUPLICATE_TITLE`	Başlık zaten var	Farklı başlık deneyin

Bakiye Hataları

Kod	Açıklama	Çözüm
`INSUFFICIENT_BALANCE`	Yetersiz bakiye	Hesabınıza bakiye yükleyin
`PAYMENT_REQUIRED`	Ödeme gerekli	Ödeme bilgilerinizi güncelleyin

Konu Hataları

Kod	Açıklama	Çözüm
`TOPIC_LIMIT_EXCEEDED`	Konu limiti aşıldı	Mevcut konuları düzenleyin
`TOPIC_NOT_FOUND`	Konu bulunamadı	Geçerli konu ID'si kullanın
`DUPLICATE_TOPIC`	Konu zaten var	Farklı konu adı deneyin

🛠️ Hata Yönetimi Best Practices

1. Comprehensive Error Handling

class APIErrorHandler {
  static async handleError(error, context = {}) {
    console.error("API Error:", error, context);

    switch (error.status) {
      case 400:
        return this.handleValidationError(error);
      case 401:
        return this.handleAuthError(error);
      case 403:
        return this.handleForbiddenError(error);
      case 429:
        return this.handleRateLimitError(error);
      case 500:
        return this.handleServerError(error);
      default:
        return this.handleUnknownError(error);
    }
  }

  static handleValidationError(error) {
    const message = error.details?.field
      ? `${error.details.field} alanında hata: ${error.message}`
      : error.message;

    return {
      type: "validation",
      message,
      field: error.details?.field,
      userAction: "Lütfen form bilgilerinizi kontrol edin",
    };
  }

  static async handleAuthError(error) {
    if (error.code === "TOKEN_EXPIRED") {
      try {
        await refreshToken();
        return {
          type: "auth",
          message: "Token yenilendi, tekrar deneyin",
          retry: true,
        };
      } catch {
        return {
          type: "auth",
          message: "Oturum süresi doldu",
          action: "redirect_login",
        };
      }
    }

    return {
      type: "auth",
      message: "Kimlik doğrulama hatası",
      action: "redirect_login",
    };
  }

  static handleRateLimitError(error) {
    const waitTime = error.retryAfter || 60;
    return {
      type: "rate_limit",
      message: `Çok fazla istek. ${waitTime} saniye bekleyin.`,
      waitTime,
      retry: true,
    };
  }
}

2. User-Friendly Error Messages

const ERROR_MESSAGES = {
  tr: {
    INSUFFICIENT_BALANCE: "Hesabınızda yeterli bakiye bulunmamaktadır.",
    TOKEN_EXPIRED: "Oturum süreniz dolmuştur. Lütfen tekrar giriş yapın.",
    TITLE_TOO_LONG: "Makale başlığı çok uzun. Lütfen kısaltın.",
    NETWORK_ERROR: "Bağlantı hatası. İnternet bağlantınızı kontrol edin.",
    SERVER_ERROR: "Sunucu hatası. Lütfen daha sonra tekrar deneyin.",
  },
};

function getUserFriendlyMessage(errorCode, language = "tr") {
  return ERROR_MESSAGES[language][errorCode] || "Beklenmeyen bir hata oluştu.";
}

3. Retry Logic

class RetryManager {
  static async executeWithRetry(operation, options = {}) {
    const {
      maxRetries = 3,
      baseDelay = 1000,
      maxDelay = 10000,
      retryCondition = (error) => error.status >= 500 || error.status === 429,
    } = options;

    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        return await operation();
      } catch (error) {
        if (attempt === maxRetries || !retryCondition(error)) {
          throw error;
        }

        const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);

        console.log(`Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
        await new Promise((resolve) => setTimeout(resolve, delay));
      }
    }
  }
}

4. Error Logging

class ErrorLogger {
  static log(error, context) {
    const logEntry = {
      timestamp: new Date().toISOString(),
      error: {
        message: error.message,
        status: error.status,
        code: error.code,
        stack: error.stack,
      },
      context,
      userAgent: navigator.userAgent,
      url: window.location.href,
    };

    // Production'da gerçek logging servisi kullanın
    console.error("API Error Log:", logEntry);

    // Kritik hataları sunucuya gönder
    if (error.status >= 500) {
      this.sendToLoggingService(logEntry);
    }
  }

  static async sendToLoggingService(logEntry) {
    try {
      await fetch("/api/logs", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(logEntry),
      });
    } catch (err) {
      console.error("Failed to send log:", err);
    }
  }
}

📋 Debug Checklist

Hata aldığınızda kontrol etmeniz gerekenler:

✅ Temel Kontroller

API endpoint URL'i doğru mu?
HTTP method doğru mu?
Content-Type header'ı ayarlandı mı?
Authorization header'ı var mı?

✅ Authentication

Access token geçerli mi?
Token süresi dolmamış mı?
Bearer prefix kullanıldı mı?

✅ Request Data

JSON formatı geçerli mi?
Zorunlu alanlar dolu mu?
Veri tipleri doğru mu?
Karakter limitleri aşılmamış mı?

✅ Network

İnternet bağlantısı var mı?
Firewall/proxy engeli var mı?
DNS çözümleme çalışıyor mu?

🆘 Destek Alma

Hata çözümlenemezse:

Hata kodunu not alın
Request/Response detaylarını kaydedin
Teknik destek ile iletişime geçin
Request ID'yi paylaşın (varsa)

Destek Kanalları:

📧 Email: api-support@seoauthor.ai
💬 Live Chat: API dokümantasyon sayfası
📱 Telefon: +90 (555) 123-4567

Hızlı Çözüm

En yaygın hatalar authentication ve validation hataları. İlk olarak token'ınızın geçerliliğini ve gönderdiğiniz verilerin formatını kontrol edin.

Rate Limiting

API çağrı limitlerini aşmamak için isteklerinizi throttle edin ve retry logic kullanın.

Güvenlik

Hata mesajlarında hassas bilgileri (şifreler, token'lar) log etmeyin veya kullanıcıya göstermeyin.

🚨 HTTP Status Kodları​

2xx - Başarılı İşlemler​

4xx - İstemci Hataları​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

404 Not Found​

409 Conflict​

422 Unprocessable Entity​

429 Too Many Requests​

5xx - Sunucu Hataları​

500 Internal Server Error​

502 Bad Gateway​

503 Service Unavailable​

🔍 Özel Hata Kodları​

Authentication Hataları​

Makale Hataları​

Bakiye Hataları​

Konu Hataları​

🛠️ Hata Yönetimi Best Practices​

1. Comprehensive Error Handling​

2. User-Friendly Error Messages​

3. Retry Logic​

4. Error Logging​

📋 Debug Checklist​

✅ Temel Kontroller​

✅ Authentication​

✅ Request Data​

✅ Network​

🆘 Destek Alma​

🚨 HTTP Status Kodları

2xx - Başarılı İşlemler

4xx - İstemci Hataları

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

5xx - Sunucu Hataları

500 Internal Server Error

502 Bad Gateway

503 Service Unavailable

🔍 Özel Hata Kodları

Authentication Hataları

Makale Hataları

Bakiye Hataları

Konu Hataları

🛠️ Hata Yönetimi Best Practices

1. Comprehensive Error Handling

2. User-Friendly Error Messages

3. Retry Logic

4. Error Logging

📋 Debug Checklist

✅ Temel Kontroller

✅ Authentication

✅ Request Data

✅ Network

🆘 Destek Alma