---
title: "Αναφορά σφαλμάτων API - φάκελος και κωδικοί κατάστασης"
description: "Η αναφορά σφαλμάτων του API του HyperCRM: οι μορφές απάντησης επιτυχίας και σφάλματος, η συσχέτιση request-id, και κάθε κωδικός με το status του."
canonical: "https://hypercrm.app/el/docs/api/errors"
lang: "el"
updated: "2026-09-14"
---

_Αναφορά API / Σφάλματα_

# Κάθε κωδικός σφάλματος, σε ένα σημείο

Κάθε απάντηση του API του HyperCRM, επιτυχής ή αποτυχημένη, ακολουθεί μία από δύο μορφές φακέλου. Αυτή η σελίδα παραθέτει και τις δύο μορφές, πώς λειτουργούν τα request id, και τον πλήρη πίνακα κωδικών σφάλματος και καταστάσεων HTTP που μπορεί να επιστρέψει ένα endpoint.

[Ξεκινήστε δωρεάν δοκιμή](/dashboard) · [Πίσω στην αναφορά API](/el/docs/api)

## Οι δύο φάκελοι

Οι επιτυχείς απαντήσεις (2xx) μοιάζουν πάντα έτσι, με το `data` να κρατά τον πόρο και το `requestId` για συσχέτιση:

```json
{
  "data": { "...": "resource-specific shape" },
  "requestId": "req_5f2c1e40-..."
}
```

Τα endpoints `POST` που δημιουργούν πόρο επιστρέφουν 201 με την ίδια μορφή. Οι απαντήσεις σφάλματος (4xx/5xx) μοιράζονται το αντίστροφο σχήμα, με σταθερό `code`, ένα ασφαλές προς εμφάνιση `message`, το ίδιο `requestId`, και προαιρετικό πίνακα `details` που υπάρχει μόνο όταν υπάρχουν ζητήματα σε επίπεδο πεδίου (π.χ. καταχωρίσεις επικύρωσης πεδίων με `path`/`message`):

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "requestId": "req_5f2c1e40-...",
    "details": [ { "path": ["firstName"], "message": "firstName is required" } ]
  }
}
```

## Request id

Κάθε απάντηση φέρει κεφαλίδα `x-request-id`, και η ίδια τιμή εμφανίζεται ως `requestId` στο σώμα. Αν το εισερχόμενο αίτημα προμηθεύει τη δική του κεφαλίδα `x-request-id` (ή `x-correlation-id`) που ταιριάζει σε ασφαλές μοτίβο, αυτή η τιμή επιστρέφεται αυτούσια για συσχέτιση αρχείων καταγραφής από την πλευρά του πελάτη· διαφορετικά ο διακομιστής παράγει μία της μορφής `req_<uuid>`.

Πίσω στον [κόμβο αναφοράς API](/el/docs/api) για τις υπόλοιπες σελίδες πόρων.

## Όλοι οι κωδικοί σφάλματος

Η κατάσταση είναι σταθερή ανά κωδικό. Ορισμένα endpoints αντικαθιστούν το μήνυμα με κάτι πιο συγκεκριμένο κρατώντας τον ίδιο κωδικό και κατάσταση, οπότε ελέγχετε τον κωδικό — ποτέ το κείμενο του μηνύματος.

| Κωδικός | Κατάσταση | Πότε συμβαίνει |
| --- | --- | --- |
| validation_failed | 400 | Ένα πεδίο απέτυχε στην επικύρωση, στάλθηκε άγνωστο πεδίο, ή το JSON ήταν κακοσχηματισμένο. Συνοδεύεται από details. |
| bad_request | 400 | Κακοσχηματισμένο αίτημα που δεν είναι αποτυχία επικύρωσης πεδίου. |
| unauthorized | 401 | Απαιτείται ταυτοποίηση. Διαφέρει από τους κωδικούς bearer token παρακάτω, που αφορούν το ίδιο το token. |
| forbidden | 403 | Ταυτοποιημένος, αλλά χωρίς δικαίωμα — για παράδειγμα εξαγωγή δεδομένων χωρίς ρόλο ιδιοκτήτη. |
| not_found | 404 | Δεν υπάρχει τέτοιος πόρος στο ιατρείο σας. Επιστρέφεται και για κακοσχηματισμένο id διαδρομής, ώστε οι δύο περιπτώσεις να μη διακρίνονται. |
| conflict | 409 | Το αίτημα συγκρούεται με την τρέχουσα κατάσταση — π.χ. διπλότυπος τίτλος ετικέτας. |
| already_submitted | 409 | Δημόσιος σύνδεσμος φόρμας που έχει ήδη υποβληθεί. |
| entries_not_billable | 409 | Έκδοση απόδειξης ή τιμολογίου για επιλεγμένες χρεώσεις, όταν κάποια δεν είναι ανεξόφλητη χρέωση του ίδιου ασθενή. |
| appointment_already_charged | 409 | Χρέωση ραντεβού που έχει ήδη χρέωση χωρίς ακύρωση. Ακυρώστε πρώτα εκείνη τη χρέωση. |
| appointment_not_chargeable | 409 | Χρέωση ραντεβού που δεν είναι επιβεβαιωμένο ραντεβού ασθενή: αίτημα, απορριφθέν, ακυρωμένο ή ληγμένο ραντεβού, υπενθύμιση ή κλειστό διάστημα. |
| token_expired | 410 | Ο δημόσιος σύνδεσμος έχει λήξει. |
| payload_too_large | 413 | Το σώμα του αιτήματος ξεπερνά το μέγιστο αποδεκτό μέγεθος. |
| recipient_tax_id_required | 422 | Ζητήθηκε τιμολόγιο για ασθενή χωρίς ΑΦΜ. Προσθέστε τον ΑΦΜ ή εκδώστε απόδειξη. |
| rate_limit_exceeded | 429 | Συμπληρώθηκε ένα όριο ρυθμού. |
| internal_error | 500 | Απρόσμενο σφάλμα διακομιστή. Δεν επιστρέφεται τίποτα για την αιτία· αναφέρετε το requestId. |
| service_unavailable | 503 | Μια εξάρτηση δεν είναι προσωρινά διαθέσιμη. |
| missing_authorization | 401 | Δεν στάλθηκε κεφαλίδα Authorization. |
| invalid_authorization_header | 401 | Η κεφαλίδα υπήρχε αλλά όχι στη μορφή Bearer <token>. |
| invalid_auth_token | 401 | Το token δεν είναι έγκυρο. |
| expired_auth_token | 401 | Το token έχει λήξει. Ανανεώστε το και δοκιμάστε ξανά. |
| revoked_auth_token | 401 | Το token έχει ανακληθεί. |
| auth_token_verification_failed | 401 | Το token δεν επαληθεύτηκε για λόγο χωρίς πιο συγκεκριμένο κωδικό. |
| disabled_auth_token | 403 | Το token επαληθεύεται, αλλά η ταυτότητα πίσω του είναι απενεργοποιημένη — εξ ου 403 και όχι 401. |
| unsupported_auth_provider | 403 | Ο συγκεκριμένος πάροχος σύνδεσης δεν γίνεται δεκτός για πρόσβαση στο API. |
| auth_provider_email_required | 403 | Ο πάροχος σύνδεσης δεν έδωσε διεύθυνση email, που απαιτείται για δημιουργία λογαριασμού. |
| user_disabled | 403 | Ο ίδιος ο λογαριασμός HyperCRM είναι απενεργοποιημένος. |
| auth_configuration_missing | 503 | Η ταυτοποίηση δεν είναι ρυθμισμένη στον διακομιστή. |

## Συχνές ερωτήσεις

### Πώς προστατεύονται τα δεδομένα των ασθενών;

Τα αρχεία ασθενών κρυπτογραφούνται κατά τη μεταφορά και την αποθήκευση, τα αρχεία φυλάσσονται ιδιωτικά και σερβίρονται μέσω συνδέσμων περιορισμένης διάρκειας, ενώ κάθε αλλαγή καταγράφεται. Το προσωπικό συνδέεται με passkeys αντί για κοινούς κωδικούς.

### Υπάρχει πάντα το `details` σε μια απάντηση σφάλματος;

Όχι. Περιλαμβάνεται μόνο όταν υπάρχουν δομημένα ζητήματα σε επίπεδο πεδίου, όπως αποτυχίες επικύρωσης πεδίων, καθεμία με διαδρομή και μήνυμα. Όταν δεν υπάρχει κάτι συγκεκριμένο για πεδίο, το κλειδί παραλείπεται εντελώς από το σώμα της απάντησης αντί να στέλνεται ως κενός πίνακας.

### Πώς συσχετίζω ένα αποτυχημένο αίτημα με αρχεία καταγραφής του διακομιστή;

Χρησιμοποιήστε την τιμή requestId από το σώμα της απάντησης, ή την ταυτόσημη κεφαλίδα απάντησης x-request-id. Αν το δικό σας αίτημα έστειλε ήδη κεφαλίδα x-request-id ή x-correlation-id στην αναμενόμενη μορφή, η ίδια τιμή επιστρέφεται αυτούσια, οπότε μπορείτε να παράγετε το δικό σας id εκ των προτέρων και να το ταιριάζετε από άκρη σε άκρη.

### Γιατί ένας απενεργοποιημένος λογαριασμός είναι 403 αντί για 401;

Επειδή το ίδιο το bearer token εξακολουθεί να είναι έγκυρο και επαληθεύεται σωστά — η ταυτότητα πίσω του είναι απενεργοποιημένη, κάτι που το HyperCRM αντιμετωπίζει ως αποτυχία εξουσιοδότησης αντί για αποτυχία αυθεντικοποίησης. Είναι σκόπιμη εξαίρεση από τη συνηθέστερη σύμβαση, τεκμηριωμένη ρητά στη σελίδα αναφοράς αυθεντικοποίησης.