# Hata Kodları

Bu sayfa, Yolcu360 Agency API'sinin döndürebileceği kapsamlı hata kodlarını ve açıklamalarını içerir. Her hata kodu HTTP
durum kodunu, detaylı açıklamayı ve çözüm için önerilen eylemleri içerir.

## Hata Yanıt Formatı

Bir hata oluştuğunda, API tutarlı bir hata yanıt formatı döndürür:

```json
{
  "code": 1001,
  "description": "Payload ayrıştırma hatası",
  "details": {
    "field": "checkInDateTime",
    "message": "Gelecek bir tarih olmalı",
    "value": "2023-01-01T10:00:00Z"
  }
}
```

### Yanıt Alanları

| Alan | Tür | Açıklama |
|  --- | --- | --- |
| `code` | integer | Benzersiz hata tanımlayıcısı |
| `description` | string | İnsan tarafından okunabilir hata açıklaması |
| `details` | object | Ek hataya özgü bilgiler (isteğe bağlı) |


## Genel Hatalar (1000-1099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 1001 | 400 | Payload ayrıştırma hatası | İstek gövdesi sözdizimini ve içerik türünü kontrol edin |
| 1002 | 400 | Doğrulama hatası | İstek verilerinin doğrulama kurallarını karşıladığını doğrulayın |
| 1003 | 400 | Parametre hatası | İstek parametrelerinin doğru olduğunu kontrol edin |


## Kimlik Doğrulama Hataları (2000-2099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 2001 | 401 | Yetkisiz | Geçerli kimlik doğrulama bilgileri sağlayın |
| 2002 | 403 | Yasak | Kullanıcı izinlerini ve erişim haklarını kontrol edin |
| 2003 | 400 | Kullanıcının hiçbir organizasyonu yok, destek ile iletişime geçin | Organizasyon atamak için destek ile iletişime geçin |
| 2004 | 401 | Geçersiz kimlik bilgileri | Kullanıcı adı ve parolanın doğru olduğunu doğrulayın |
| 2005 | 400 | Geçersiz organizasyon türü. Lütfen destek ile iletişime geçin | Organizasyon türü sorunları için destek ile iletişime geçin |


## Konum Hataları (3000-3099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 3001 | 404 | Konum bulunamadı | Konum kimliğini kontrol edin veya geçerli konum arayın |
| 3002 | 400 | Geçersiz konum sorgusu | Konum sorgu parametrelerinin doğru olduğunu doğrulayın |


## Arama Hataları (4000-4099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 4001 | 404 | Kampanya bulunamadı | Mevcut kampanyalardan geçerli kampanya kimliği kullanın |
| 4002 | 400 | Geçersiz ürün kodu | Ürün kodu formatını ve kullanılabilirliğini doğrulayın |
| 4003 | 400 | Geçersiz arama kimliği | Arama sonuçlarından geçerli arama kimliği kullanın |
| 4004 | 404 | Ürün bulunamadı | Ürün kimliğini kontrol edin veya mevcut ürünleri arayın |
| 4005 | 400 | Geçersiz giriş zamanı | Giriş için geçerli gelecek tarihi kullanın |
| 4006 | 400 | Geçersiz çıkış zamanı | Çıkış için geçerli gelecek tarihi kullanın |
| 4007 | 400 | Geçersiz rezervasyon süresi | Çıkış tarihinin giriş tarihinden sonra olduğundan emin olun |
| 4008 | 400 | Geçersiz komisyon | Komisyon değerinin gereksinimleri karşıladığını kontrol edin |
| 4009 | 400 | Ofis tedarikçileri farklı | Aynı tedarikçiden ofisleri kullanın |
| 4010 | 400 | Geçersiz para birimi kodu | Geçerli ISO 4217 para birimi kodu kullanın |


## Sipariş Hataları (5000-5099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 5001 | 404 | Acenta konfigürasyonu bulunamadı. Bazı konfigürasyonlar henüz ayarlanmamış olabilir. Lütfen destek ile iletişime geçin. | Acenta konfigürasyonu için destek ile iletişime geçin |
| 5002 | 404 | Sipariş bulunamadı | Sipariş kimliğinin doğru olduğunu doğrulayın |
| 5003 | 400 | Organizasyonun birincil fatura adresi yok | Organizasyona birincil fatura adresi ekleyin |
| 5004 | 400 | Acenta bireysel fatura adresi ekleyemez | Acente için özel fatura yetkisi kapalı: organizasyonun kayıtlı adresini kullanmak için `billing` göndermeyin ya da yetki için Yolcu360 ile iletişime geçin |
| 5005 | 400 | Sipariş açık değil. Kapalı veya iptal edilmiş olabilir. | Değişiklikten önce sipariş durumunu kontrol edin |
| 5006 | 400 | Sipariş kalemi siparişe ait değil | Sipariş kaleminin belirtilen siparişe ait olduğunu doğrulayın |
| 5007 | 400 | Siparişin ödemesi yok | Siparişe ödeme bilgisi ekleyin |
| 5008 | 404 | Kalem bulunamadı | Kalem kimliğinin doğru olduğunu doğrulayın |
| 5009 | 400 | Kalem durumu geçerli değil | Kalem durumunun istenen işleme izin verdiğini kontrol edin |
| 5010 | 400 | Yolcu kimlik numarası geçersiz | Geçerli kimlik numarası formatı sağlayın |
| 5011 | 400 | Yolcu pasaport numarası geçersiz | Geçerli pasaport numarası formatı sağlayın |
| 5012 | 500 | Rezervasyon başarısız | Rezervasyonu yeniden deneyin veya destek ile iletişime geçin |
| 5013 | 400 | Sipariş iptal edilemez | Sipariş durumunun iptale izin verdiğini kontrol edin |
| 5014 | 400 | Ürün miktarı geçersiz | İzin verilen sınırlar içinde geçerli miktar kullanın |
| 5015 | 400 | Geçersiz ürün kodu | Mevcut ürünlerden geçerli ürün kodu kullanın |
| 5016 | 400 | Yolcu doğum tarihi geçersiz | Geçerli doğum tarihi formatı sağlayın |
| 5017 | 400 | Sınırlı kredi kullanılamaz | Acenta sınırlı kredi için yetkilendirilmemiş |
| 5018 | 400 | Tam kredi kullanılamaz | Acenta tam kredi için yetkilendirilmemiş |
| 5019 | 400 | Sipariş ödeme türü, tahsilat ödeme yöntemi ile eşleşmiyor | Ödeme türünün tahsilat yöntemi ile eşleştiğini doğrulayın |


## Ödeme Hataları (6000-6099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 6001 | 400 | İstenen para birimi için kredi limiti bulunamadı | İstenen para birimi için kredi limiti ayarlayın |
| 6002 | 400 | Ödeme başarısız | Ödeme detaylarını kontrol edin ve tekrar deneyin |
| 6003 | 400 | Geçersiz ödeme türü | Desteklenen ödeme türünü kullanın (kredi kartı veya limit) |
| 6004 | 400 | Araç zaten rezerve edilmiş | Farklı bir araç veya zaman dilimi seçin |
| 6005 | 400 | Geçersiz kart bilgisi | Kredi kartı detaylarının doğru olduğunu doğrulayın |
| 6006 | 400 | Geçersiz taksit sayısı | Geçerli taksit seçeneği seçin |
| 6007 | 500 | İsteğiniz işlenirken bir hata oluştu | Lütfen daha sonra tekrar deneyin veya sorun devam ederse destek ile iletişime geçin |
| 6008 | 400 | Test ortamında ödemeler yalnızca "Yolcutest" tedarikçisi için desteklenmektedir | Test ortamında Yolcutest tedarikçisini kullanın |


## Transfer Hataları (8000-8099)

| Kod | HTTP Durumu | Açıklama | Çözüm |
|  --- | --- | --- | --- |
| 8001 | 400 | Geçersiz transfer arama isteği | Arama alanlarının doğrulama kurallarına uyduğunu kontrol edin |
| 8002 | 400 | Organizasyon transfer için yapılandırılmamış | Organizasyonunuzda transferin etkinleştirilmesi için destek ile iletişime geçin |
| 8003 | 404 | Transfer ürünü bulunamadı veya süresi doldu | Yeni bir arama yapın; teklifler aramadan yaklaşık 30 dakika sonra sona erer |
| 8004 | 400 | Geçersiz transfer sipariş isteği | Yolcu ve fatura alanlarının doğrulama kurallarına uyduğunu kontrol edin |
| 8005 | 400 | Yolcu sayısı araç kapasitesini aşıyor | Yolcu sayısına yetecek koltuğa sahip bir araç seçin |
| 8006 | 400 | Transfer siparişi oluşturulamadı | Yeni bir aramayla tekrar deneyin; sorun sürerse destek ile iletişime geçin |
| 8007 | 400 | Geçersiz fatura bilgisi | Fatura alanlarını kontrol edin (taxIdentifier ve zipCode zorunludur) |
| 8008 | 400 | Transfer ödemesi başarısız | Kredi limitinizi kontrol edin; tekrar denemeden önce sipariş durumuna bakın |
| 8009 | 400 | Transfer siparişi zaten ödenmiş | Sipariş durumunu sipariş detayı endpoint'i ile kontrol edin |
| 8010 | 400 | Ödeme başarılı ancak rezervasyon tamamlanamadı | Sipariş detayını kontrol edin ve destek ile iletişime geçin; ödemeniz kaybolmaz |
| 8011 | 404 | Transfer siparişi bulunamadı | Sipariş kimliğinin doğru olduğunu kontrol edin |
| 8012 | 400 | Transfer siparişi iptal edilemez | Önce iptal uygunluğunu kontrol edin; gerekirse destek ile iletişime geçin |
| 8013 | 400 | İptal başarılı ancak iade işlenemedi | İade için destek ile iletişime geçin |


## Hata İşleme En İyi Uygulamaları

### İstemci Uygulaması

```javascript
async function handleApiResponse(response) {
    if (!response.ok) {
        const error = await response.json();

        switch (error.code) {
            case 2001: // Yetkisiz
                await refreshToken();
                return retryRequest();

            case 6002: // Ödeme başarısız
                showPaymentError('Ödeme başarısız. Lütfen detaylarınızı kontrol edip tekrar deneyin.');
                return;

            case 4004: // Ürün bulunamadı
                showSearchMessage('Ürün bulunamadı. Lütfen farklı bir arama deneyin.');
                return;

            case 1002: // Doğrulama hatası
                showValidationError(error.description, error.details);
                return;

            default:
                showGenericError(error.description);
        }
    }

    return response.json();
}

function getRetryDelay(headers) {
    const retryAfter = headers.get('Retry-After');
    return retryAfter ? parseInt(retryAfter) * 1000 : 5000;
}
```

### Hata Sınıflandırması

#### Yeniden Denenebilir Hatalar

- Rezervasyon başarısız (5012)
- Ağ zaman aşımları
- Servis kullanılamazlığı


#### Yeniden Denenemeyen Hatalar

- Kimlik doğrulama hataları (2001-2005)
- Doğrulama hataları (1001-1003)
- Bulunamadı hataları (3001, 4001, 4004, 5002, 5008)
- Ödeme hataları (6001-6008)


### Yeniden Deneme Stratejisi

```javascript
async function makeRequestWithRetry(url, options, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            const response = await fetch(url, options);

            if (response.ok) {
                return response;
            }

            if (!isRetriableError(response.status) || attempt === maxRetries) {
                throw new Error(`İstek başarısız: ${response.status}`);
            }

            // Üstel geri çekilme
            const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
            await new Promise(resolve => setTimeout(resolve, delay));

        } catch (error) {
            if (attempt === maxRetries) {
                throw error;
            }
        }
    }
}

function isRetriableError(status, code) {
    // Yeniden denenebilir belirli hata kodlarını kontrol et
    if (code === 5012) return true; // Rezervasyon başarısız

    // Yeniden denenebilir HTTP durum kodlarını kontrol et
    return [500, 502, 503, 504].includes(status);
}
```

### Hata Günlükleme

```javascript
function logError(error, context) {
    const errorData = {
        timestamp: new Date().toISOString(),
        code: error.code,
        description: error.description,
        context: context,
        userAgent: navigator.userAgent,
        url: window.location.href
    };

    // Günlükleme servisine gönder
    fetch('/api/logs/error', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(errorData)
    });

    // Geliştirme ortamında konsola logla
    if (process.env.NODE_ENV === 'development') {
        console.error('API Hatası:', errorData);
    }
}
```

## Destek ve Sorun Giderme

### İletişim Bilgileri

Kalıcı hatalar veya destek için:

- **E-posta**: api-support@yolcu360.com
- **Dokümantasyon**: [docs.yolcu360.com](https://docs.yolcu360.com)
- **Durum Sayfası**: [status.yolcu360.com](https://status.yolcu360.com)


### Destek İçin Gerekli Bilgiler

Destek ile iletişime geçerken şunları ekleyin:

1. Hata kodu ve açıklaması
2. İstek zaman damgası
3. İstek kimliği (yanıt başlıklarında mevcutsa)
4. Yeniden üretme adımları
5. API anahtarı (yalnızca son 4 karakter)


### Yaygın Çözüm Adımları

1. **API Durumunu Kontrol Edin**: Durum sayfasında servis durumunu doğrulayın
2. **İsteği Doğrulayın**: İstek formatının dokümantasyonla eşleştiğinden emin olun
3. **Kimlik Bilgilerini Kontrol Edin**: API anahtarının aktif ve izinlere sahip olduğunu doğrulayın
4. **Hız Sınırlarını Gözden Geçirin**: Hız sınırlarının aşılıp aşılmadığını kontrol edin
5. **Test Ortamını Deneyin**: İsteği test ortamında deneyin
6. **Entegrasyonu Güncelleyin**: En son API sürümünü kullandığınızdan emin olun