Acente girişi
Ana sayfa / Geliştirici API / Hata kodları

API hata kodları

Entegrasyon sırasında aldığınız hataların anlamı, olası nedenleri ve çözüm adımları. Yanıtlarda error_code veya error.code alanına bakın.

Dokümantasyon Geliştirici girişi

Yanıt formatı

Kısa link API (/link/v1/):

{
  "success": false,
  "error": {
    "code": "VWS-A004",
    "message": "Domain yetkisi yok.",
    "hint": "Tarayıcı isteklerinde Origin/Referer izinli domain listesinde olmalı.",
    "docs": "https://vize.ws/gelistirici/hatalar#VWS-A004"
  }
}

Vize araçları API (/vize-araclari/v1/):

{
  "status": "error",
  "error_code": "VWS-V001",
  "message": "from ve to parametreleri zorunludur.",
  "hint": "Her iki ülke kodu ISO 3166-1 alpha-2 olmalıdır.",
  "docs": "https://vize.ws/gelistirici/hatalar#VWS-V001"
}

Kimlik doğrulama

VWS-A001 HTTP 401

API anahtarı gerekli.

Authorization başlığında Bearer token gönderin.

Olası neden
İstekte Authorization: Bearer vws_… başlığı yok veya boş.
Çözüm
Panelden aldığınız anahtarı her isteğe ekleyin: Authorization: Bearer vws_…
Örnek
curl -H "Authorization: Bearer vws_…" "https://api.vize.ws/vize-araclari/v1/countries"
VWS-A002 HTTP 401

Geçersiz veya iptal edilmiş API anahtarı.

Anahtarın doğru kopyalandığından ve aktif olduğundan emin olun.

Olası neden
Gönderilen token veritabanında bulunamadı, süresi doldu veya devre dışı bırakıldı.
Çözüm
Geliştirici panelinden anahtarı yenileyin veya yeni anahtar talep edin.
VWS-A003 HTTP 403

Bu anahtar için yetki yok.

İlgili endpoint için gerekli kapsam anahtarınızda tanımlı değil.

Olası neden
Anahtarınızda istenen kapsam (link veya vize_araclari) yok.
Çözüm
Panelden kapsam değişikliği talep edin veya doğru kapsamlı anahtarı kullanın.
VWS-A004 HTTP 403

Domain yetkisi yok.

Tarayıcı isteklerinde Origin/Referer izinli domain listesinde olmalı.

Olası neden
İstek kaynağı (Origin veya Referer) anahtarınıza tanımlı domainlerle eşleşmiyor.
Çözüm
Sunucu tarafı (backend) istekleri domain kontrolünden muaf olabilir; tarayıcıdan çağırıyorsanız domaini panele ekletin.
VWS-A005 HTTP 403

IP adresi izinli değil.

Legacy link API secret yalnızca tanımlı IP'lerden kabul edilir.

Olası neden
Sunucu IP'niz allowed_panel_ips listesinde değil.
Çözüm
vws_ anahtarına geçin veya IP whitelist için destek talebi açın.

Genel

VWS-G001 HTTP 405

HTTP metodu desteklenmiyor.

Endpoint yalnızca belirli HTTP metodlarını kabul eder.

Olası neden
GET yerine POST veya tersi kullanıldı.
Çözüm
Dokümantasyondaki metodu kullanın (vize araçları: GET, link oluşturma: POST).
VWS-G002 HTTP 404

Endpoint bulunamadı.

URL yolunu ve sürümü kontrol edin.

Olası neden
Tanınmayan path veya yanlış yazılmış endpoint.
Çözüm
Base URL: https://api.vize.ws — örnek: /vize-araclari/v1/check?from=TR&to=DE

Kısa link

VWS-L001 HTTP 404

Link bulunamadı veya süresi dolmuş.

Kısa kod geçersiz, silinmiş veya süresi dolmuş olabilir.

Olası neden
Veritabanında eşleşen aktif link kaydı yok.
Çözüm
Kodu doğrulayın veya yeni kısa link oluşturun.
VWS-L002 HTTP 400

Geçerli long_url gerekli.

JSON gövdesinde long_url veya url alanı zorunludur.

Olası neden
URL eksik, boş veya http(s) formatında değil.
Çözüm
POST /link/v1/ — {"long_url":"https://example.com/sayfa"}
VWS-L003 HTTP 500

Benzersiz kısa kod üretilemedi.

Geçici sunucu sorunu; kısa süre sonra tekrar deneyin.

Olası neden
Slug üretiminde çakışma çözülemedi.
Çözüm
İsteği birkaç saniye sonra tekrarlayın; devam ederse destek talebi açın.
VWS-L004 HTTP 405

Desteklenmeyen link API isteği.

POST /link/v1/ veya GET /link/v1/resolve/{code} kullanın.

Olası neden
Tanınmayan path veya metod kombinasyonu.
Çözüm
Dokümantasyondaki örnek URL'leri birebir kullanın.

Vize araçları

VWS-V001 HTTP 400

from ve to parametreleri zorunludur.

Her iki ülke kodu ISO 3166-1 alpha-2 olmalıdır.

Olası neden
check endpoint'ine from veya to gönderilmedi.
Çözüm
GET /vize-araclari/v1/check?from=TR&to=DE
VWS-V002 HTTP 400

Geçersiz ülke kodu formatı.

İki harfli büyük harf ISO kodu kullanın (TR, DE, US).

Olası neden
Parametre 2 harfli ISO2 formatına uymuyor.
Çözüm
Ülke kodlarını büyük harfe çevirin ve countries listesinden doğrulayın.
VWS-V003 HTTP 404

Bu ülke kombinasyonu için vize bilgisi bulunamadı.

Kodlar geçerli olabilir ancak veritabanında kayıt yok.

Olası neden
Pasaport-hedef çifti için vize gereksinimi tanımlı değil.
Çözüm
ISO kodlarını /countries ile doğrulayın; eksik veri için destek talebi açın.
VWS-V004 HTTP 400

country parametresi zorunludur.

Pasaport ülkesi ISO2 kodu gönderin (from/country/passport alias desteklenir).

Olası neden
passport-power endpoint'ine geçerli country/from parametresi yok.
Çözüm
GET /vize-araclari/v1/passport-power?from=TR
VWS-V005 HTTP 404

Ülke bulunamadı.

ISO kodu countries listesinde yok.

Olası neden
Veritabanında eşleşen ülke kaydı bulunamadı.
Çözüm
GET /vize-araclari/v1/countries ile geçerli kodları listeleyin.
VWS-V006 HTTP 500

Sorgu sırasında sunucu hatası oluştu.

Geçici bir sorun olabilir; isteği tekrarlayın.

Olası neden
Veritabanı veya uygulama katmanında beklenmeyen hata.
Çözüm
Yanıttaki error_code ile destek talebinde bize bildirin.
VWS-V007 HTTP 405

Yalnızca GET istekleri kabul edilir.

Vize araçları API salt okunurdur.

Olası neden
POST, PUT veya DELETE ile istek gönderildi.
Çözüm
Tüm vize araçları endpoint'lerini GET ile çağırın.