Помилки

Усі помилки повертаються у єдиному форматі:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "01HXY2A7ZM0ABCDEF",
    "details": null
  }
}

• code — машиночитний snake_case код, стабільний, ніколи не змінюється без мажорного бампа
• message — людиночитне пояснення, англійською
• request_id — ULID запиту, цитуй при зверненні в підтримку
• details — опціональний об’єкт з контекстом (у 422 — список провалених полів)

HTTP-коди

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

Error codes

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

Код	HTTP	Значення
missing_api_key	401	Header X-Api-Key не надіслано
invalid_api_key	401	Ключ не існує або revoked
insufficient_scope	403	Ключ не має прав на цю дію (наприклад, не master-ключ)

Білінг

Код	HTTP	Значення
credits_exhausted	402	Місячний бюджет кредитів вичерпано
subscription_inactive	402	Підписка касована або expired
overage_disabled	402	Overage вимкнено в settings, а бюджет вичерпано

Rate limiting

Код	HTTP	Значення
rate_limit_exceeded	429	Перевищено ліміт RPM. Містить retry_after_seconds

Валідація

Код	HTTP	Значення
invalid_request	400	Битий JSON або відсутній обов’язковий header
validation_failed	422	Одне або кілька полів провалили Zod-валідацію. details містить масив { field, message }

Приклад 422:

{
  "error": {
    "code": "validation_failed",
    "message": "Request body validation failed.",
    "request_id": "01HXY2A7ZM...",
    "details": [
      { "field": "datetime",  "message": "Invalid ISO 8601 datetime" },
      { "field": "latitude",  "message": "Must be between -90 and 90" }
    ]
  }
}

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

Код	HTTP	Значення
location_out_of_range	422	Координати поза дозволеним діапазоном для цього ендпоінту (наприклад, Arctic для Placidus)
date_out_of_range	422	Дата поза межами Swiss Ephemeris (до -13000 або після 17000)
house_system_unsupported	422	Полярний регіон для Placidus/Koch — запропонуй Whole Sign або Equal
ephemeris_error	500	Внутрішня помилка обчислення — рідкісний випадок, цитуй request_id

Серверні

Код	HTTP	Значення
internal_error	500	Неочікувана помилка. Логуємо з stack trace, цитуй request_id
service_unavailable	503	Деплой або scheduled maintenance. Retry через 30 сек
dependency_failure	503	Збій в DB або іншій залежності. Retry з експоненційним backoff

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

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

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),
  });

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

  return res.json();
}

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

Коди — стабільна частина API. Свіч по code, не по message (текст повідомлень може уточнюватись без бампа).

Запит підтримки

Для звернення надішли на [email protected]:

1. request_id з відповіді
2. Ендпоінт і скорочений JSON body (без секретів)
3. Очікувана поведінка vs фактична
4. Часовий пояс і приблизний час запиту (UTC)

Відповідь — у межах SLA твого плану (48 год Starter, 24 год Pro, власна для Enterprise).