Помилки

Усі помилки повертаються у єдиному форматі — ok: false плюс об’єкт error:

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

code — машиночитний UPPER_SNAKE_CASE код, стабільний, не змінюється без мажорного бампа. Свіч по ньому, не по message.
message — людиночитне пояснення, англійською. Текст може уточнюватись без бампа.
details — опціональний. Для INVALID_INPUT це масив { path, message } по кожному проваленому полю.
request_id — додається лише до 5xx та BAD_JSON відповідей; цитуй його при зверненні в підтримку.

HTTP-коди

Статус	Значення
`200 OK`	Успіх
`400 Bad Request`	Битий JSON, відсутні поля або провалена Zod-валідація
`401 Unauthorized`	Відсутній або невалідний `X-Api-Key`
`402 Payment Required`	Потрібен вищий тариф / пак, або підписка неактивна
`403 Forbidden`	Ключ валідний, але немає прав (scope, origin, suspended)
`404 Not Found`	Ресурс, ключ або job не існує
`422 Unprocessable Entity`	Вхід валідний, але рушій не зміг порахувати
`429 Too Many Requests`	Перевищено rate limit, вичерпано кредити або spend-cap
`500 Internal Server Error`	Внутрішня помилка — з нашого боку, цитуй `request_id`
`503 Service Unavailable`	AI-шлюз / черга тимчасово недоступні

Error codes

Автентифікація (401)

Код	Значення
`MISSING_API_KEY`	Header `X-Api-Key` не надіслано
`INVALID_API_KEY`	Ключ не існує або revoked
`MISSING_BEARER`	Схема `Authorization: Bearer` обрана, але токен відсутній
`WRONG_AUTH_METHOD`	На `/v1/me/` (Bearer-only) надіслано `X-Api-Key`. Для перевірки ключа — `GET /v1/auth/keys/me`; для викликів API — будь-який `/v1/` з `X-Api-Key`

Права (403)

Код	Значення
`INSUFFICIENT_SCOPE`	Ключ не має прав на цю дію
`DOMAIN_MISMATCH` / `FORBIDDEN_ORIGIN`	Origin запиту не в allow-list ключа
`KEY_SUSPENDED`	Ключ призупинено

Білінг (402)

Код	Значення
`PLAN_UPGRADE_REQUIRED`	Ендпоінт потребує вищого тарифу або add-on пака
`PLAN_PACK_MISMATCH`	Ендпоінт входить у пак, якого немає на ключі
`SUBSCRIPTION_EXPIRED`	Підписка касована або expired

Rate limiting та кредити (429)

Код	Значення
`RATE_LIMIT`	Перевищено ліміт RPM. Відповідь містить header `Retry-After: <sec>`
`CREDITS_EXHAUSTED`	Місячний бюджет кредитів вичерпано
`SPEND_CAP_REACHED`	Досягнуто ліміт витрат на AI-ендпоінти

Валідація (400)

Код	Значення
`INVALID_INPUT`	Одне або кілька полів провалили Zod-валідацію. `details` — масив `{ path, message }`
`MISSING_FIELDS`	Відсутнє обов’язкове поле
`BAD_JSON`	Битий JSON у тілі запиту

Приклад 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" }
    ]
  }
}

Розрахункові помилки (422)

Код	Значення
`CALCULATION_ERROR`	Вхід валідний, але рушій не зміг порахувати (наприклад, полярна широта для Placidus). Спробуй Whole Sign / Equal або іншу дату.

Серверні

Код	HTTP	Значення
`INTERNAL_ERROR`	500	Неочікувана помилка. Логуємо зі stack trace, цитуй `request_id`
`GATEWAY_UNAVAILABLE` / `AI_UNAVAILABLE` / `LLM_UNAVAILABLE`	503	AI-шлюз недоступний. Retry з експоненційним backoff
`QUEUE_UNAVAILABLE`	503	Черга фонових задач недоступна

Обробка в клієнтському коді

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

Свіч по code, не по message. Офіційні SDK (@astroway/sdk, astroway) кидають типізовані підкласи помилок за HTTP-статусом (AuthenticationError, RateLimitError, BadRequestError …), тож код обробки писати не доведеться.