# Σφάλματα

Όλα τα σφάλματα επιστρέφονται σε ενιαία μορφή - `ok: false` συν ένα αντικείμενο `error`:

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

- `code`: ένας αναγνώσιμος από μηχανή κώδικας `UPPER_SNAKE_CASE`, **σταθερός**, δεν αλλάζει χωρίς σημαντική αναβάθμιση. Κάνε switch σε αυτόν, όχι στο `message`.
- `message`: μια αναγνώσιμη από άνθρωπο επεξήγηση, στα Αγγλικά. Το κείμενο μπορεί να τροποποιηθεί χωρίς αναβάθμιση.
- `details`: προαιρετικό. Για το `INVALID_INPUT` είναι ένας πίνακας `{ path, message }` για κάθε πεδίο που απέτυχε. Για το `INVALID_FIELD` προστίθεται το `expected` με το κανονικό όνομα του πεδίου σε κάθε στοιχείο.
- `docs`: προαιρετικό, ένας σύνδεσμος προς μια ενότητα αυτής της σελίδας, όταν υπάρχει μια πιο λεπτομερής εξήγηση για τον κώδικα.
- `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` | Ο πόρος, το κλειδί ή η εργασία δεν υπάρχει |
| `422 Unprocessable Entity` | Η είσοδος είναι έγκυρη, αλλά η μηχανή δεν μπόρεσε να υπολογίσει |
| `429 Too Many Requests` | Υπέρβαση ορίου ρυθμού (rate limit), εξάντληση κρέντιτ ή ορίου δαπανών (spend-cap) |
| `500 Internal Server Error` | Εσωτερικό σφάλμα - από την πλευρά μας, αναφέρεις το `request_id` |
| `503 Service Unavailable` | Η πύλη AI / η ουρά είναι προσωρινά μη διαθέσιμη |

## Κωδικοί σφαλμάτων

### Έλεγχος ταυτότητας (401)

| Κωδικός | Σημασία |
|---|---|
| `MISSING_API_KEY` | Το header `X-Api-Key` δεν στάλθηκε |
| `INVALID_API_KEY` | Το κλειδί δεν υπάρχει ή έχει ανακληθεί |
| `MISSING_BEARER` | Επιλέχθηκε το σχήμα `Authorization: Bearer`, αλλά το token λείπει |
| `WRONG_AUTH_METHOD` | Στο `/v1/me/*` (μόνο Bearer) στάλθηκε `X-Api-Key`. Για έλεγχο κλειδιού - `GET /v1/auth/keys/me`. Για κλήσεις API - οποιοδήποτε `/v1/*` με `X-Api-Key` |

### Δικαιώματα (403)

| Κωδικός | Σημασία |
|---|---|
| `INSUFFICIENT_SCOPE` | Το κλειδί δεν έχει δικαιώματα για αυτήν την ενέργεια |
| `DOMAIN_MISMATCH` / `FORBIDDEN_ORIGIN` | Το origin της αίτησης δεν βρίσκεται στη λίστα επιτρεπόμενων (allow-list) του κλειδιού |
| `ENDPOINT_NOT_IN_SCOPE` | Το κλειδί περιορίζεται από μια λίστα endpoints (`allowed_endpoints`), και αυτή η διαδρομή δεν περιλαμβάνεται στη λίστα. Το `details` αναφέρει τη λίστα |
| `KEY_SUSPENDED` | Το κλειδί έχει ανασταλεί |

### Χρέωση (402)

| Κωδικός | Σημασία |
|---|---|
| `PLAN_UPGRADE_REQUIRED` | Το endpoint απαιτεί υψηλότερο πρόγραμμα ή πακέτο add-on |
| `PLAN_PACK_MISMATCH` | Το endpoint περιλαμβάνεται σε ένα πακέτο που δεν υπάρχει στο κλειδί |
| `SUBSCRIPTION_EXPIRED` | Η περίοδος πληρωμής έληξε πριν από περισσότερες από 3 ημέρες. Τις πρώτες 3 ημέρες μετά τη λήξη, οι αιτήσεις εξακολουθούν να εξυπηρετούνται σύμφωνα με το πρόγραμμα και φέρουν το header `X-Subscription-Grace-Ends`. Το `details` περιέχει `expired_at`, `grace_ended_at` και `renew_url` |

### Περιορισμός ρυθμού και κρέντιτ (429)

| Κωδικός | Σημασία |
|---|---|
| `RATE_LIMIT` | Υπέρβαση ορίου RPM. Η απάντηση περιέχει το header `Retry-After: <sec>` |
| `CREDITS_EXHAUSTED` | Ο μηνιαίος προϋπολογισμός κρέντιτ έχει εξαντληθεί. Στο Free αυτό είναι οριστικό μέχρι την επαναφορά. Τα επί πληρωμή προγράμματα, αντίθετα, μεταβαίνουν σε overage, εάν δεν σταματήσουν από το όριο δαπανών |
| `SPEND_CAP_REACHED` | Έχει επιτευχθεί το μηνιαίο όριο δαπανών του λογαριασμού για overage. Όριο $0 σημαίνει "διακοπή στο όριο του προγράμματος": αντί για χρέωση overage, λαμβάνεις αυτόν τον κωδικό. Το `details` περιέχει `cap`, `used` και `reset_at` |
| `KEY_BUDGET_EXHAUSTED` | Το κλειδί έχει εξαντλήσει τον δικό του προϋπολογισμό (`credits_cap_cycle`). Τα κρέντιτ στον λογαριασμό μπορεί να παραμένουν: ο περιορισμός αφορά συγκεκριμένα αυτό το κλειδί |

### Επικύρωση (400)

| Κωδικός | Σημασία |
|---|---|
| `INVALID_INPUT` | Ένα ή περισσότερα πεδία απέτυχαν στην επικύρωση Zod. Το `details` είναι ένας πίνακας `{ path, message }` |
| `INVALID_FIELD` | Το σώμα περιέχει ένα σύντομο όνομα πεδίου αντί για το κανονικό. Δες παρακάτω |
| `MISSING_FIELDS` | Λείπει ένα υποχρεωτικό πεδίο |
| `BAD_JSON` | Κατεστραμμένο JSON στο σώμα της αίτησης |
| `BODY_TOO_DEEP` | Το JSON στο σώμα είναι ενσωματωμένο σε βάθος μεγαλύτερο από 64 επίπεδα |

Παράδειγμα `400`:

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

Τα endpoints διαγραμμάτων δέχονται μόνο πλήρη ονόματα πεδίων. Οι σύντομες μορφές απορρίπτονται με `400` και δεν διαβάζονται σιωπηλά:

| Στάλθηκε | Κανονικό πεδίο | Τι αναμένεται |
|---|---|---|
| `lat` | `latitude` | δεκαδικοί βαθμοί, ο βορράς είναι θετικός |
| `lng`, `lon`, `long` | `longitude` | δεκαδικοί βαθμοί, η ανατολή είναι θετική |
| `tz` με αριθμό, `tzOffset`, `utcOffset`, `timezone_offset` | `timezoneOffset` | αριθμός ωρών από UTC, π.χ. `5.75` |
| `tz` με όνομα, `timeZone`, `time_zone` | `timezone` | όνομα ζώνης IANA, π.χ. `Europe/Kyiv`, ή `auto` |

Η απάντηση παραθέτει **όλα** τα πεδία που βρέθηκαν ταυτόχρονα, με τη σειρά του σώματος της αίτησης, οπότε η μετονομασία γίνεται με μία μόνο διέλευση:

```json
{
  "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` υποδεικνύει την πλήρη διαδρομή, οπότε στη συναστρία είναι ορατό ποιου ακριβώς είναι το διάγραμμα: `chart1.lat`, και όχι απλώς `lat`.

Ο ίδιος κωδικός επιστρέφεται όταν το `timezone` δεν μπορεί να αναλυθεί: κενή τιμή, συντομογραφία όπως `EST` (αυτό είναι σταθερό -5 όλο το χρόνο, οπότε η Νέα Υόρκη τον Ιούλιο θα είναι λάθος κατά μία ώρα), όνομα που δεν υπάρχει στη βάση δεδομένων ζωνών ώρας, μετατόπιση γραμμένη ως κείμενο, όπως `+03:00`, ή `auto` χωρίς `latitude` και `longitude`. Το μήνυμα υποδεικνύει τι να στείλεις αντ' αυτού, και το `path` δείχνει το αντικείμενο, για παράδειγμα `chart2.timezone`.

Δύο πράγματα που πρέπει να λάβεις υπόψη.

**Αυτό δεν είναι κατάργηση.** Τα σύντομα ονόματα δεν ήταν ποτέ μέρος της σύμβασης και δεν εμφανίζονταν στο `/openapi.json` ως πεδία σώματος. Πριν από τις 2026-08-01, δεν λειτουργούσαν, αλλά αγνοούνταν σιωπηλά: οι συντεταγμένες είχαν μια προεπιλεγμένη τιμή μηδέν, οπότε το διάγραμμα υπολογιζόταν για 0°N 0°E σε UTC. Ο Ωροσκόπος, οι οίκοι και όλα τα παράγωγά τους ήταν λανθασμένα, και η απάντηση δεν το ανέφερε. Επομένως, οι σύντομες μορφές δεν γίνονται ξανά δεκτές: δύο ονόματα για ένα πεδίο για πάντα, και το `tz` είναι επιπλέον διφορούμενο (αριθμός ή όνομα ζώνης).

**Το ενσωματωμένο `point` είναι κάτι διαφορετικό.** Στα `/v1/acg-zones`, `/v1/acg/by-category`, `/v1/ccg-analysis` και `/v1/eclipse-analysis`, το αντικείμενο `point: { lat, lng }` είναι δηλωμένα ονόματα πεδίων και γίνονται δεκτά.

### Ελλιπείς συντεταγμένες: `400` από 2026-11-09

Το σωστό όνομα πεδίου είναι η μισή δουλειά. Το σώμα **χωρίς** `latitude` και `longitude` έδινε επίσης `200`, επειδή οι συντεταγμένες είχαν μια προεπιλεγμένη τιμή μηδέν, και η απάντηση περιέγραφε 0°N 0°E.

Μέχρι τις 2026-11-09, μια τέτοια αίτηση εξακολουθούσε να λειτουργεί, με `Deprecation: true`, `Sunset`, `Warning` και το πεδίο `_warning` στο σώμα. Από τις 2026-11-09, αυτό είναι `400 INVALID_INPUT` με `latitude is required, in decimal degrees`.

Τα ρητά `latitude: 0, longitude: 0` είναι έγκυρα και συνεχίζουν να είναι: το ζήτημα είναι το ελλιπές πεδίο, όχι η τιμή. Το `timezoneOffset` διατηρεί την προεπιλεγμένη τιμή μηδέν, επειδή το μηδέν εκεί σημαίνει UTC. Η `city` δεν αντικαθιστά τις συντεταγμένες: κανείς δεν την γεωκωδικοποιεί. Ο έλεγχος εφαρμόζεται μόνο σε αντικείμενα που φέρουν ταυτόχρονα `date` και `time`.

### Σφάλματα υπολογισμού (422)

| Κωδικός | Σημασία |
|---|---|
| `CALCULATION_ERROR` | Η είσοδος είναι έγκυρη, αλλά η μηχανή δεν μπόρεσε να υπολογίσει (π.χ., πολικό πλάτος για Placidus). Δοκίμασε Whole Sign / Equal ή άλλη ημερομηνία. |

### Σφάλματα διακομιστή

| Κωδικός | HTTP | Σημασία |
|---|---|---|
| `INTERNAL_ERROR` | 500 | Απροσδόκητο σφάλμα. Καταγράφουμε με stack trace, αναφέρεις το `request_id` |
| `GATEWAY_UNAVAILABLE` / `AI_UNAVAILABLE` / `LLM_UNAVAILABLE` | 503 | Η πύλη AI δεν είναι διαθέσιμη. Επανάληψη με εκθετικό backoff |
| `QUEUE_UNAVAILABLE` | 503 | Η ουρά εργασιών παρασκηνίου δεν είναι διαθέσιμη |

## Χειρισμός στον κώδικα του πελάτη

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

Κάνε switch στο `code`, όχι στο `message`. Τα επίσημα SDK ([`@astroway/sdk`](https://www.npmjs.com/package/@astroway/sdk), [`astroway`](https://pypi.org/project/astroway/)) εκτοξεύουν τυποποιημένες υποκλάσεις σφαλμάτων ανάλογα με την κατάσταση HTTP (`AuthenticationError`, `RateLimitError`, `BadRequestError` …), οπότε δεν θα χρειαστεί να γράψεις κώδικα χειρισμού.

## Αίτημα υποστήριξης

Για να επικοινωνήσεις, στείλε στο [support@astroway.info](mailto:support@astroway.info):

1. Το `request_id` από την απάντηση (αν είναι `5xx`)
2. Το endpoint και ένα συνοπτικό JSON body (χωρίς μυστικά)
3. Αναμενόμενη συμπεριφορά έναντι πραγματικής
4. Ζώνη ώρας και κατά προσέγγιση ώρα αίτησης (UTC)

Η απάντηση θα δοθεί εντός του SLA του προγράμματός σου (48 ώρες Starter, 24 ώρες Pro, προσαρμοσμένο για Enterprise).
