Chyby

Všechny chyby se vracejí v jednotném formátu: ok: false plus objekt error:

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

code: strojově čitelný kód ve tvaru UPPER_SNAKE_CASE, stabilní, nemění se bez zvýšení major verze. Větvi podle něj, ne podle message.
message: vysvětlení čitelné pro člověka, anglicky. Text se může upřesnit i bez zvýšení verze.
details: nepovinné. Pro INVALID_INPUT je to pole { path, message } pro každé neúspěšné pole. Pro INVALID_FIELD se ke každému prvku přidává expected s kanonickým jménem pole.
docs: nepovinné, odkaz na sekci této stránky, pokud pro kód existuje podrobnější vysvětlení.
request_id: přidává se jen k odpovědím 5xx a BAD_JSON; uveď ho, když se obracíš na podporu.

HTTP kódy

Status	Význam
`200 OK`	Úspěch
`400 Bad Request`	Poškozený JSON, chybějící pole nebo neúspěšná Zod validace
`401 Unauthorized`	Chybějící nebo neplatný `X-Api-Key`
`402 Payment Required`	Je potřeba vyšší tarif / balíček, nebo předplatné není aktivní
`403 Forbidden`	Klíč je platný, ale chybí oprávnění (scope, origin, suspended)
`404 Not Found`	Zdroj, klíč nebo job neexistuje
`422 Unprocessable Entity`	Vstup je platný, ale výpočetní jádro ho nedokázalo spočítat
`429 Too Many Requests`	Překročen rate limit, vyčerpány kredity nebo spend cap
`500 Internal Server Error`	Interní chyba na naší straně, uveď `request_id`
`503 Service Unavailable`	AI brána / fronta je dočasně nedostupná

Chybové kódy

Autentizace (401)

Kód	Význam
`MISSING_API_KEY`	Hlavička `X-Api-Key` nebyla odeslána
`INVALID_API_KEY`	Klíč neexistuje nebo byl zneplatněn
`MISSING_BEARER`	Je zvoleno schéma `Authorization: Bearer`, ale token chybí
`WRONG_AUTH_METHOD`	Na `/v1/me/` (jen Bearer) byl odeslán `X-Api-Key`. Pro kontrolu klíče použij `GET /v1/auth/keys/me`; pro volání API libovolný `/v1/` s `X-Api-Key`

Oprávnění (403)

Kód	Význam
`INSUFFICIENT_SCOPE`	Klíč nemá oprávnění k této akci
`DOMAIN_MISMATCH` / `FORBIDDEN_ORIGIN`	Origin požadavku není v allow-listu klíče
`ENDPOINT_NOT_IN_SCOPE`	Klíč je omezen seznamem endpointů (`allowed_endpoints`) a tato cesta v seznamu není. `details` seznam uvádí
`KEY_SUSPENDED`	Klíč je pozastaven

Fakturace (402)

Kód	Význam
`PLAN_UPGRADE_REQUIRED`	Endpoint vyžaduje vyšší tarif nebo doplňkový balíček
`PLAN_PACK_MISMATCH`	Endpoint patří do balíčku, který klíč nemá
`SUBSCRIPTION_EXPIRED`	Zaplacené období skončilo před více než 3 dny. První 3 dny po skončení se požadavky ještě obsluhují podle tarifu a nesou hlavičku `X-Subscription-Grace-Ends`. `details` obsahuje `expired_at`, `grace_ended_at` a `renew_url`

Rate limiting a kredity (429)

Kód	Význam
`RATE_LIMIT`	Překročen limit RPM. Odpověď obsahuje hlavičku `Retry-After: <sec>`
`CREDITS_EXHAUSTED`	Měsíční rozpočet kreditů je vyčerpán
`SPEND_CAP_REACHED`	Dosažen limit útraty na AI endpointy
`KEY_BUDGET_EXHAUSTED`	Klíč vyčerpal vlastní rozpočet (`credits_cap_cycle`). Kredity na účtu přitom mohou zbývat: omezení se týká právě tohoto klíče

Validace (400)

Kód	Význam
`INVALID_INPUT`	Jedno nebo více polí neprošlo Zod validací. `details` je pole `{ path, message }`
`INVALID_FIELD`	Tělo obsahuje krátké jméno pole místo kanonického. Viz níže
`MISSING_FIELDS`	Chybí povinné pole
`BAD_JSON`	Poškozený JSON v těle požadavku

Příklad 400:

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

Chart endpointy přijímají jen plná jména polí. Krátké tvary se odmítají s 400, místo aby se potichu četly:

Odesláno	Kanonické pole	Co se očekává
`lat`	`latitude`	desetinné stupně, sever kladně
`lng`, `lon`, `long`	`longitude`	desetinné stupně, východ kladně
`tz` s číslem, `tzOffset`, `utcOffset`, `timezone_offset`	`timezoneOffset`	počet hodin od UTC, např. `5.75`
`tz` s názvem, `timeZone`, `time_zone`	`timezone`	název zóny IANA, např. `Europe/Kyiv`, nebo `auto`

Odpověď vyjmenuje všechna nalezená pole najednou, v pořadí těla požadavku, takže přejmenování zvládneš jedním průchodem:

{
  "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 uvádí úplnou cestu, takže v synastrii je vidět, o čí horoskop jde: chart1.lat, ne jen lat.

Tentýž kód se vrací, když se timezone nepodaří rozebrat: prázdná hodnota, zkratka jako EST (to je pevných -5 po celý rok, takže New York v červenci vyjde o hodinu špatně), název, který v databázi časových pásem není, posun zapsaný textem jako +03:00, nebo auto bez latitude a longitude. Zpráva napoví, co poslat místo toho, a path ukazuje na objekt, například chart2.timezone.

Na dvě věci je dobré myslet.

Nejde o deprecaci. Krátká jména nikdy nebyla součástí kontraktu a v /openapi.json se jako pole těla nevyskytovala. Do 2026-08-01 nefungovala, ale byla potichu ignorována: souřadnice mají výchozí nulu, takže se horoskop počítal pro 0°N 0°E v UTC. Ascendent, domy a vše od nich odvozené bylo špatně a odpověď o tom neinformovala. Proto se krátké tvary zpět nepřijímají: dvě jména pro jedno pole navždy, a tz je navíc nejednoznačné (číslo, nebo název zóny).

Vnořený point je jiná věc. V /v1/acg-zones, /v1/acg/by-category, /v1/ccg-analysis a /v1/eclipse-analysis je objekt point: { lat, lng } s deklarovanými jmény polí a ty projdou.

Chybějící souřadnice: `400` od 2026-11-09

Správné jméno pole je jen polovina úspěchu. Tělo bez latitude a longitude také vracelo 200, protože souřadnice měly výchozí nulu, a odpověď popisovala 0°N 0°E.

Do 2026-11-09 takový požadavek funguje, ale odpověď nese Deprecation: true, Sunset, Warning a pole _warning v těle. Od 2026-11-09 je to 400 INVALID_INPUT s latitude is required, in decimal degrees.

Explicitní latitude: 0, longitude: 0 jsou dál platné: jde o chybějící pole, ne o hodnotu. timezoneOffset si výchozí nulu zachovává, protože nula tam znamená UTC. city souřadnice nenahrazuje: nikdo ho negeokóduje. Kontrola se uplatňuje jen na objekty, které nesou zároveň date i time.

Výpočetní chyby (422)

Kód	Význam
`CALCULATION_ERROR`	Vstup je platný, ale jádro ho nedokázalo spočítat (například polární šířka pro Placidus). Zkus Whole Sign / Equal nebo jiné datum.

Serverové

Kód	HTTP	Význam
`INTERNAL_ERROR`	500	Neočekávaná chyba. Logujeme se stack trace, uveď `request_id`
`GATEWAY_UNAVAILABLE` / `AI_UNAVAILABLE` / `LLM_UNAVAILABLE`	503	AI brána je nedostupná. Opakuj s exponenciálním backoffem
`QUEUE_UNAVAILABLE`	503	Fronta úloh na pozadí je nedostupná

Zpracování v klientském kódu

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

Větvi podle code, ne podle message. Oficiální SDK (@astroway/sdk, astroway) vyhazují typované podtřídy chyb podle HTTP statusu (AuthenticationError, RateLimitError, BadRequestError …), takže kód pro zpracování psát nemusíš.