Hatalar

Tüm hatalar tek bir biçimde döndürülür: ok: false artı bir error nesnesi:

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

• code: makine tarafından okunabilir UPPER_SNAKE_CASE kodu, kararlıdır, major sürüm artışı olmadan değişmez. message’a göre değil, buna göre switch yapın.
• message: insan tarafından okunabilir açıklama, İngilizce. Metin sürüm artışı olmadan netleştirilebilir.
• details: isteğe bağlı. INVALID_INPUT için bu, başarısız olan her alan için { path, message } dizisidir. INVALID_FIELD için her öğeye alanın kanonik adıyla birlikte expected eklenir.
• docs: isteğe bağlı, kod için daha ayrıntılı bir açıklama olduğunda bu sayfanın ilgili bölümüne bağlantı.
• request_id: yalnızca 5xx ve BAD_JSON yanıtlarına eklenir; destekle iletişime geçerken bunu belirtin.

HTTP kodları

Durum	Anlamı
200 OK	Başarılı
400 Bad Request	Bozuk JSON, eksik alanlar veya başarısız Zod doğrulaması
401 Unauthorized	X-Api-Key eksik veya geçersiz
402 Payment Required	Daha yüksek bir plan / paket gerekiyor veya abonelik aktif değil
403 Forbidden	Anahtar geçerli, ancak yetki yok (scope, origin, suspended)
404 Not Found	Kaynak, anahtar veya job mevcut değil
422 Unprocessable Entity	Girdi geçerli, ancak motor hesaplayamadı
429 Too Many Requests	Rate limit aşıldı, krediler veya spend-cap tükendi
500 Internal Server Error	Dahili hata: bizim tarafımızda, request_id’yi belirtin
503 Service Unavailable	AI gateway / kuyruk geçici olarak kullanılamıyor

Hata kodları

Kimlik doğrulama (401)

Kod	Anlamı
MISSING_API_KEY	X-Api-Key başlığı gönderilmedi
INVALID_API_KEY	Anahtar mevcut değil veya iptal edilmiş
MISSING_BEARER	Authorization: Bearer şeması seçilmiş, ancak token yok
WRONG_AUTH_METHOD	/v1/me/* (yalnızca Bearer) adresine X-Api-Key gönderildi. Anahtarı kontrol etmek için: GET /v1/auth/keys/me; API çağrıları için: X-Api-Key ile herhangi bir /v1/*

Yetkiler (403)

Kod	Anlamı
INSUFFICIENT_SCOPE	Anahtarın bu işlem için yetkisi yok
DOMAIN_MISMATCH / FORBIDDEN_ORIGIN	İsteğin Origin’i anahtarın izin listesinde değil
ENDPOINT_NOT_IN_SCOPE	Anahtar bir endpoint listesiyle (allowed_endpoints) sınırlandırılmış ve bu yol listede yok. details listeyi belirtir
KEY_SUSPENDED	Anahtar askıya alınmış

Faturalandırma (402)

Kod	Anlamı
PLAN_UPGRADE_REQUIRED	Endpoint daha yüksek bir plan veya add-on paketi gerektiriyor
PLAN_PACK_MISMATCH	Endpoint, anahtarda bulunmayan bir pakete dahil
SUBSCRIPTION_EXPIRED	Ödenmiş dönem 3 günden daha uzun süre önce sona erdi. Sona erdikten sonraki ilk 3 gün boyunca istekler hâlâ plana göre hizmet görür ve X-Subscription-Grace-Ends başlığını taşır. details expired_at, grace_ended_at ve renew_url içerir

Rate limiting ve krediler (429)

Kod	Anlamı
RATE_LIMIT	RPM limiti aşıldı. Yanıt Retry-After: <sec> başlığını içerir
CREDITS_EXHAUSTED	Aylık kredi bütçesi tükendi
SPEND_CAP_REACHED	AI endpoint’leri için harcama limitine ulaşıldı
KEY_BUDGET_EXHAUSTED	Anahtar kendi bütçesini (credits_cap_cycle) tüketti. Hesapta bu sırada kredi kalmış olabilir: kısıtlama yalnızca bu anahtar için geçerlidir

Doğrulama (400)

Kod	Anlamı
INVALID_INPUT	Bir veya birden fazla alan Zod doğrulamasını geçemedi. details: { path, message } dizisi
INVALID_FIELD	Gövde, kanonik ad yerine kısa bir alan adı içeriyor. Aşağıya bakın
MISSING_FIELDS	Zorunlu bir alan eksik
BAD_JSON	İstek gövdesinde bozuk JSON

400 örneği:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Invalid input: expected string, received undefined",
    "details": [
      { "path": "date", "message": "Invalid input: expected string, received undefined" },
      { "path": "time", "message": "Invalid input: expected string, received undefined" }
    ]
  }
}

INVALID_FIELD

Harita endpoint’leri yalnızca tam alan adlarını kabul eder. Kısa biçimler sessizce okunmaz, 400 ile reddedilir:

Gönderilen	Kanonik alan	Beklenen
lat	latitude	ondalık derece, kuzey pozitif
lng, lon, long	longitude	ondalık derece, doğu pozitif
sayı içeren tz, tzOffset, utcOffset, timezone_offset	timezoneOffset	UTC’den saat farkı sayısı, örn. 5.75
ad içeren tz, timeZone, time_zone	timezone	IANA bölge adı, örn. Europe/Kyiv veya auto

Yanıt, bulunan tüm alanları istek gövdesindeki sırayla tek seferde listeler, böylece yeniden adlandırma tek geçişte yapılır:

{
  "ok": false,
  "error": {
    "code": "INVALID_FIELD",
    "message": "Unsupported fields: \"tz\", \"lat\", \"lng\". Rename them to \"timezoneOffset\", \"latitude\", \"longitude\". See details for what each one expects.",
    "details": [
      { "path": "tz",  "expected": "timezoneOffset", "message": "numeric hours from UTC, e.g. 5.75; a zone name goes in timezone" },
      { "path": "lat", "expected": "latitude",  "message": "decimal degrees, north positive" },
      { "path": "lng", "expected": "longitude", "message": "decimal degrees, east positive" }
    ],
    "docs": "https://api.astroway.info/en/errors/#invalid_field"
  }
}

path tam yolu belirtir, bu yüzden synastry’de hangi haritanın söz konusu olduğu görülür: yalnızca lat değil, chart1.lat.

Aynı kod, timezone ayrıştırılamadığında da döndürülür: boş bir değer, EST gibi bir kısaltma (bu yıl boyunca sabit -5’tir, yani New York temmuzda bir saat yanlış çıkar), saat dilimi veritabanında olmayan bir ad, +03:00 gibi metin olarak yazılmış bir fark ya da latitude ve longitude olmadan auto. Mesaj bunun yerine ne gönderileceğini söyler, path ise nesneyi gösterir, örneğin chart2.timezone.

Dikkat edilmesi gereken iki nokta var.

Bu bir kullanımdan kaldırma değildir. Kısa adlar hiçbir zaman sözleşmenin parçası olmadı ve /openapi.json içinde gövde alanları olarak yer almadı. 2026-08-01’e kadar çalışmıyorlardı, sessizce yok sayılıyorlardı: koordinatların varsayılanı sıfırdır, bu yüzden harita UTC’ye göre 0°N 0°E için hesaplanıyordu. Yükselen, evler ve onlardan türeyen her şey yanlıştı ve yanıt bunu bildirmiyordu. Bu yüzden kısa biçimler geri kabul edilmiyor: bir alan için sonsuza dek iki ad olurdu, üstelik tz belirsizdir (sayı mı, bölge adı mı).

İç içe point farklı bir şeydir. /v1/acg-zones, /v1/acg/by-category, /v1/ccg-analysis ve /v1/eclipse-analysis içinde point: { lat, lng } nesnesi bildirilmiş alan adlarıdır ve geçerlidir.

Eksik koordinatlar: 2026-11-09’dan itibaren 400

Doğru alan adı işin yarısıdır. latitude ve longitude içermeyen bir gövde de 200 veriyordu, çünkü koordinatların varsayılanı sıfırdı ve yanıt 0°N 0°E’yi tanımlıyordu.

2026-11-09’a kadar böyle bir istek çalışır, ancak yanıt Deprecation: true, Sunset, Warning başlıklarını ve gövdede _warning alanını taşır. 2026-11-09’dan itibaren bu, latitude is required, in decimal degrees mesajıyla 400 INVALID_INPUT olur.

Açık latitude: 0, longitude: 0 geçerli olmaya devam eder: sorun değerde değil, eksik alandadır. timezoneOffset varsayılan sıfırını korur, çünkü orada sıfır UTC anlamına gelir. city koordinatların yerini tutmaz: onu kimse geocode etmez. Kontrol yalnızca aynı anda hem date hem time taşıyan nesnelere uygulanır.

Hesaplama hataları (422)

Kod	Anlamı
CALCULATION_ERROR	Girdi geçerli, ancak motor hesaplayamadı (örneğin, Placidus için kutupsal enlem). Whole Sign / Equal ya da başka bir tarih deneyin.

Sunucu hataları

Kod	HTTP	Anlamı
INTERNAL_ERROR	500	Beklenmeyen hata. Stack trace ile loglanır, request_id’yi belirtin
GATEWAY_UNAVAILABLE / AI_UNAVAILABLE / LLM_UNAVAILABLE	503	AI gateway kullanılamıyor. Üstel backoff ile yeniden deneyin
QUEUE_UNAVAILABLE	503	Arka plan görev kuyruğu kullanılamıyor

İstemci kodunda ele alma

type ApiError = {
  ok: false;
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id?: string;
  };
};

async function chart(input: ChartInput) {
  const res = await fetch('https://api.astroway.info/v1/chart', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ASTROWAY_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });

  const body = await res.json();
  if (!body.ok) {
    throw new AstrowayError(body.error.code, body.error.message, body.error.request_id);
  }

  return body.data;
}

class AstrowayError extends Error {
  constructor(
    public code: string,
    message: string,
    public requestId?: string,
  ) {
    super(`[${code}] ${message}${requestId ? ` (request_id=${requestId})` : ''}`);
  }
}

message’a göre değil, code’a göre switch yapın. Resmî SDK’lar (@astroway/sdk, astroway) HTTP durumuna göre tiplendirilmiş hata alt sınıfları fırlatır (AuthenticationError, RateLimitError, BadRequestError …), böylece hata işleme kodu yazmanız gerekmez.

Destek talebi

Destek için support@astroway.info adresine şunları gönderin:

1. Yanıttaki request_id (5xx ise)
2. Endpoint ve kısaltılmış JSON gövdesi (sırlar olmadan)
3. Beklenen davranış ile gerçekleşen davranış
4. Saat dilimi ve isteğin yaklaşık zamanı (UTC)

Yanıt, planınızın SLA’sı dahilinde verilir (Starter için 48 saat, Pro için 24 saat, Enterprise için kendine özgü).