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

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

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

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

Κάθε απάντηση του API ακολουθεί έναν από τους δύο φακέλους, με τρεις εξαιρέσεις: τα endpoints OAuth /oauth/token και /oauth/register χρησιμοποιούν το τυπικό σώμα σφάλματος OAuth (error, error_description), και οι εξαγωγές CSV επιστρέφουν αρχείο.

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

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

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

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

Το αντικείμενο detail

Ξεχωριστά από τον πίνακα details, μια άρνηση στην οποία μπορεί να αντιδράσει ο client φέρει ένα αντικείμενο detail με τον αναγνώσιμο από μηχανή λόγο, για παράδειγμα detail.feature σε άρνηση πακέτου ή detail.limit και detail.used σε όριο. Τα κλειδιά που χρησιμοποιούνται είναι feature, resource, limit, used, requiredPlan, cost, remaining, resetsAt, reason, since, mode, practiceName και practiceLogoUrl. Διαβάστε τα με το όνομά τους και αγνοήστε ένα κλειδί που δεν γνωρίζετε: προστίθενται καθώς τα χρειάζονται νέες αρνήσεις.

Κεφαλίδες ορίων ρυθμού

Μια απάντηση 429 φέρει Retry-After σε δευτερόλεπτα, ποτέ κάτω από 1, μαζί με RateLimit-Limit, RateLimit-Remaining και RateLimit-Reset (δευτερόλεπτα μέχρι να μηδενιστεί το παράθυρο). Μια επιτυχής απάντηση δεν φέρει κανένα από αυτά, οπότε διαβάστε το υπόλοιπο από το 429 που έτσι κι αλλιώς χειρίζεστε. Ανά λεπτό, το REST επιτρέπει 300 αιτήματα ανά χρήστη, από τα οποία 120 εγγραφές, και 600 ανά διεύθυνση IP· το endpoint MCP επιτρέπει 120 ανά access token.

Τα endpoints OAuth είναι διαφορετικά

Τα /oauth/token, /oauth/register και /oauth/revoke απαντούν στη γραμματική του OAuth αντί στον φάκελο παραπάνω: error και error_description, με την κατάσταση στη γραμμή απάντησης. Οι κωδικοί είναι οι καταχωρισμένοι του OAuth, οπότε μια τυπική βιβλιοθήκη client τους καταλαβαίνει ήδη: invalid_request, invalid_client, invalid_grant, unsupported_grant_type και invalid_target (400), server_error για οτιδήποτε 5xx, και temporarily_unavailable για αίτημα που κόπηκε από όριο, το οποίο διατηρεί την κατάσταση 429 ώστε ένας client που ξέρει μόνο τη λίστα του OAuth να επιβραδύνει σωστά.

Request id

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

Πίσω στον κόμβο αναφοράς API για τις υπόλοιπες σελίδες πόρων.