Hata İşleme

Standart hata kodlarıyla hataları doğru şekilde işleyin.

Hata Yanıt Formatı

Tüm API hataları tutarlı bir JSON formatını izler.

{
  "error": {
    "code": "error_code_here",
    "message": "A human-readable description of the error."
  }
}

Hata Kodları

Durum	Kod	Açıklama
`401`	`missing_api_key`	İstekte X-API-Key başlığı sağlanmadı.
`401`	`invalid_api_key`	Sağlanan API anahtarı geçersiz, süresi dolmuş veya iptal edilmiş.
`402`	`quota_exceeded`	Aylık istek kotası aşıldı.
`422`	`invalid_image`	image alanı eksik, geçersiz base64 veya 5MB'yi aşıyor.
`422`	`invalid_request`	İstek gövdesi geçerli JSON değil.
`502`	`inference_error`	ML hizmeti geçici olarak kullanılamıyor. Backoff ile yeniden deneyin.

Hata Yanıt Örnekleri

API Anahtarı Eksik (401)

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the X-API-Key header."
  }
}

Geçersiz Görüntü (422)

{
  "error": {
    "code": "invalid_image",
    "message": "Image exceeds the maximum size of 5 MB."
  }
}

Çıkarım Hatası (502)

{
  "error": {
    "code": "inference_error",
    "message": "ML inference service is temporarily unavailable. Please retry."
  }
}

En İyi Uygulamalar

Yanıt gövdesini ayrıştırmadan önce her zaman HTTP durum kodunu kontrol edin.
502 hataları için üstel geri çekilme uygulayın.
Yanıt başlıkları aracılığıyla kota kullanımını izleyin.
401 veya 422 hatalarını yeniden denemeyin.
Programatik hata işleme için error.code alanını kullanın.

Yeniden Deneme Örneği

Üstel geri çekilmeli JavaScript örneği:

async function analyzePalm(imageBase64, apiKey, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(
      "https://api.trace-line.site/v1/palm/analyze",
      {
        method: "POST",
        headers: {
          "X-API-Key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ image: imageBase64 }),
      }
    );

    if (res.ok) return res.json();

    const error = await res.json();

    // Only retry on transient errors
    if (res.status !== 502) throw error;

    // Exponential backoff: 1s, 2s, 4s
    await new Promise((r) =>
      setTimeout(r, 1000 * Math.pow(2, attempt))
    );
  }

  throw new Error("Max retries exceeded");
}