Hibák

Minden hiba egységes formátumban érkezik: ok: false, plusz egy error objektum:

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

• code: géppel olvasható UPPER_SNAKE_CASE kód, stabil, főverzió-emelés nélkül nem változik. Erre ágazz el, ne a message mezőre.
• message: ember által olvasható magyarázat, angolul. A szöveg verzióemelés nélkül is pontosodhat.
• details: opcionális. Az INVALID_INPUT esetén ez egy { path, message } tömb minden elbukott mezőre. Az INVALID_FIELD esetén minden elem mellé egy expected is kerül a kanonikus mezőnévvel.
• docs: opcionális, link ennek az oldalnak egy fejezetére, ha a kódhoz részletesebb magyarázat tartozik.
• request_id: csak 5xx és BAD_JSON válaszokhoz kerül hozzá; idézd, amikor a supporthoz fordulsz.

HTTP-kódok

Státusz	Jelentés
200 OK	Siker
400 Bad Request	Hibás JSON, hiányzó mezők vagy elbukott Zod-validáció
401 Unauthorized	Hiányzó vagy érvénytelen X-Api-Key
402 Payment Required	Magasabb csomag / pack szükséges, vagy az előfizetés inaktív
403 Forbidden	A kulcs érvényes, de nincs jogosultsága (scope, origin, suspended)
404 Not Found	Az erőforrás, a kulcs vagy a job nem létezik
422 Unprocessable Entity	A bemenet érvényes, de a motor nem tudta kiszámolni
429 Too Many Requests	Túllépted a rate limitet, elfogytak a kreditek vagy elérted a spend-capet
500 Internal Server Error	Belső hiba, a mi oldalunkon; idézd a request_id értéket
503 Service Unavailable	Az AI-átjáró / a sor átmenetileg nem érhető el

Hibakódok

Hitelesítés (401)

Kód	Jelentés
MISSING_API_KEY	Az X-Api-Key fejléc nem lett elküldve
INVALID_API_KEY	A kulcs nem létezik, vagy vissza lett vonva
MISSING_BEARER	Az Authorization: Bearer séma van kiválasztva, de a token hiányzik
WRONG_AUTH_METHOD	A /v1/me/* útvonalra (csak Bearer) X-Api-Key érkezett. A kulcs ellenőrzéséhez: GET /v1/auth/keys/me; API-hívásokhoz: bármely /v1/* X-Api-Key fejléccel

Jogosultságok (403)

Kód	Jelentés
INSUFFICIENT_SCOPE	A kulcsnak nincs jogosultsága ehhez a művelethez
DOMAIN_MISMATCH / FORBIDDEN_ORIGIN	A kérés originje nincs a kulcs engedélyezési listáján
ENDPOINT_NOT_IN_SCOPE	A kulcs endpointlistára van korlátozva (allowed_endpoints), és ez az útvonal nincs rajta. A details megnevezi a listát
KEY_SUSPENDED	A kulcs fel van függesztve

Számlázás (402)

Kód	Jelentés
PLAN_UPGRADE_REQUIRED	Az endpointhoz magasabb csomag vagy add-on pack szükséges
PLAN_PACK_MISMATCH	Az endpoint egy olyan packhoz tartozik, amely nincs a kulcson
SUBSCRIPTION_EXPIRED	A kifizetett időszak több mint 3 napja lejárt. A lejárat utáni első 3 napban a kéréseket még a csomag szerint szolgáljuk ki, és X-Subscription-Grace-Ends fejlécet hordoznak. A details tartalmazza az expired_at, grace_ended_at és renew_url mezőket

Rate limiting és kreditek (429)

Kód	Jelentés
RATE_LIMIT	Túllépted az RPM-limitet. A válasz Retry-After: <sec> fejlécet tartalmaz
CREDITS_EXHAUSTED	Elfogyott a havi kreditkeret
SPEND_CAP_REACHED	Elérted az AI-endpointokra vonatkozó költési limitet
KEY_BUDGET_EXHAUSTED	A kulcs kimerítette a saját keretét (credits_cap_cycle). A fiókon közben maradhat kredit: a korlátozás csak erre a kulcsra vonatkozik

Validáció (400)

Kód	Jelentés
INVALID_INPUT	Egy vagy több mező elbukott a Zod-validáción. A details egy { path, message } tömb
INVALID_FIELD	A törzs rövid mezőnevet tartalmaz a kanonikus helyett. Lásd lent
MISSING_FIELDS	Hiányzik egy kötelező mező
BAD_JSON	Hibás JSON a kérés törzsében

Példa 400-ra:

{
  "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

A chart-endpointok csak a teljes mezőneveket fogadják el. A rövid alakokat 400-zal elutasítják, nem pedig csendben beolvassák:

Elküldve	Kanonikus mező	Mit várunk
lat	latitude	tizedes fok, észak pozitív
lng, lon, long	longitude	tizedes fok, kelet pozitív
tz számmal, tzOffset, utcOffset, timezone_offset	timezoneOffset	órák száma UTC-től, pl. 5.75
tz névvel, timeZone, time_zone	timezone	IANA-zónanév, pl. Europe/Kyiv, vagy auto

A válasz egyszerre sorolja fel az összes talált mezőt, a kérés törzsének sorrendjében, így az átnevezés egyetlen menetben elvégezhető:

{
  "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"
  }
}

A path a teljes útvonalat adja meg, így a synastryben látszik, pontosan kinek a képletéről van szó: chart1.lat, nem egyszerűen lat.

Ugyanez a kód jön vissza akkor is, ha a timezone nem értelmezhető: üres érték, egy olyan rövidítés, mint az EST (ez egész évben fix -5, így New York júliusban egy órával tévedne), egy név, amely nincs benne az időzóna-adatbázisban, szövegként írt eltolás, mint a +03:00, vagy auto latitude és longitude nélkül. Az üzenet megmondja, mit küldj helyette, a path pedig az objektumra mutat, például chart2.timezone.

Két dologra érdemes figyelni.

Ez nem elavulás. A rövid nevek sosem voltak a szerződés részei, és törzsmezőként sosem szerepeltek a /openapi.json fájlban. 2026-08-01 előtt nem működtek, hanem csendben figyelmen kívül maradtak: a koordináták alapértéke nulla, így a képlet 0°N 0°E-re számolódott UTC szerint. Az aszcendens, a házak és minden, ami ezekből következik, hibás volt, a válasz pedig erről nem szólt. Ezért a rövid alakokat nem vesszük vissza: egy mezőre örökre két név, a tz ráadásul kétértelmű (szám vagy zónanév).

A beágyazott point más eset. A /v1/acg-zones, /v1/acg/by-category, /v1/ccg-analysis és /v1/eclipse-analysis endpointokban a point: { lat, lng } objektum deklarált mezőneveket tartalmaz, és ezek átmennek.

Hiányzó koordináták: 400 2026-11-09-től

A helyes mezőnév a feladat fele. Egy latitude és longitude nélküli törzs is 200-at adott, mert a koordináták alapértéke nulla volt, és a válasz a 0°N 0°E pontot írta le.

2026-11-09-ig egy ilyen kérés működik, de a válasz Deprecation: true, Sunset, Warning fejlécet és a törzsben _warning mezőt hordoz. 2026-11-09-től ez 400 INVALID_INPUT, latitude is required, in decimal degrees üzenettel.

Az explicit latitude: 0, longitude: 0 továbbra is érvényes: a kérdés a hiányzó mező, nem az érték. A timezoneOffset megtartja a nulla alapértéket, mert ott a nulla UTC-t jelent. A city nem helyettesíti a koordinátákat: senki sem geokódolja. Az ellenőrzés csak azokra az objektumokra vonatkozik, amelyek egyszerre tartalmaznak date és time mezőt.

Számítási hibák (422)

Kód	Jelentés
CALCULATION_ERROR	A bemenet érvényes, de a motor nem tudta kiszámolni (például sarkvidéki szélesség Placidus esetén). Próbáld Whole Sign / Equal házrendszerrel vagy más dátummal.

Szerveroldali

Kód	HTTP	Jelentés
INTERNAL_ERROR	500	Váratlan hiba. Stack trace-szel naplózzuk; idézd a request_id értéket
GATEWAY_UNAVAILABLE / AI_UNAVAILABLE / LLM_UNAVAILABLE	503	Az AI-átjáró nem érhető el. Próbáld újra exponenciális backoffal
QUEUE_UNAVAILABLE	503	A háttérfeladatok sora nem érhető el

Kezelés a kliensoldali kódban

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})` : ''}`);
  }
}

A code alapján ágazz el, ne a message alapján. A hivatalos SDK-k (@astroway/sdk, astroway) HTTP-státusz szerint típusos hiba-alosztályokat dobnak (AuthenticationError, RateLimitError, BadRequestError …), így hibakezelő kódot nem kell írnod.

Supportkérés

Ha a supporthoz fordulsz, küldd el a support@astroway.info címre:

1. A válaszból a request_id értéket (ha 5xx-ről van szó)
2. Az endpointot és a rövidített JSON-törzset (titkok nélkül)
3. A várt és a tényleges viselkedést
4. Az időzónát és a kérés hozzávetőleges időpontját (UTC)

A válasz a csomagod SLA-ján belül érkezik (48 óra Starter, 24 óra Pro, egyedi az Enterprise esetén).