Σφάλματα

Τα σφάλματα μοιράζονται έναν φάκελο (δείτε την επισκόπηση). Διακλαδώστε τη λογική σας βάσει του code, καταγράφετε το meta.request_id και αντιμετωπίζετε το message ως αγγλικό κείμενο για ανθρώπους.

Σφάλματα πελάτη

Κωδικός	Κατάσταση	Σημασία και τι να κάνετε
validation_failed	400	Ένα πεδίο απέτυχε στην επικύρωση. Το field το κατονομάζει· το details εξηγεί. Διορθώστε το πεδίο.
bad_request	400	Το αίτημα δεν μπόρεσε να διαβαστεί καθόλου: κακοσχηματισμένο JSON, κατεστραμμένη ροή Content-Encoding, διακοπτόμενο σώμα. Δεν υπάρχει πεδίο για διόρθωση· ελέγξτε τη μεταφορά.
validation_error	400	Το X-Account-Id στάλθηκε σε endpoint που το απαγορεύει (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Ο cursor σελιδοποίησης είναι παλαιότερος από 24 ώρες. Ξεκινήστε τη λίστα από την αρχή.
unauthenticated	401	Λείπει ή είναι μη έγκυρο το token. Ανανεώστε τη συνεδρία ή ελέγξτε το κλειδί.
invalid_signature	401	Μια υπογραφή webhook δεν επαληθεύτηκε. Δείτε Webhooks.
forbidden	403	Το token είναι έγκυρο αλλά δεν έχει το δικαίωμα.
account_context_mismatch	403	Το X-Account-Id δεν ταιριάζει με τον λογαριασμό του token. Η εικόνα του πελάτη για την τρέχουσα εταιρεία έχει αποκλίνει· διαβάστε την ξανά από τη συνεδρία.
not_found	404	Ο πόρος δεν υπάρχει ή ανήκει σε άλλον λογαριασμό ή ιστότοπο. Το API δεν διακρίνει ποτέ τις δύο περιπτώσεις.
conflict	409	Σύγκρουση κατάστασης: αισιόδοξο κλείδωμα, περιορισμός μοναδικότητας ή ενέργεια που δεν επιτρέπεται στην τρέχουσα κατάσταση (για παράδειγμα εγγραφή σε συγχωνευμένη συνομιλία).
idempotency_key_conflict	409	Το Idempotency-Key επαναχρησιμοποιήθηκε με διαφορετικό σώμα.
payload_too_large	413	Το σώμα υπερβαίνει το όριο για αυτή την οικογένεια endpoints.
unsupported_media_type	415	Λάθος Content-Type.
unprocessable	422	Έγκυρο JSON, αλλά ένας επιχειρηματικός κανόνας το απέρριψε (για παράδειγμα χρονοθυρίδα κράτησης εκτός ωραρίου εργασίας).
storage_quota_exceeded	422	Ο λογαριασμός έφτασε το όριο αποθήκευσης του προγράμματός του. Το details περιέχει used_bytes, quota_bytes και requested_bytes· ελευθερώστε χώρο ή αναβαθμίστε.
rate_limited	429	Επιβραδύνετε. Τηρήστε το Retry-After και το details.retry_after_seconds.

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

Κωδικός	Κατάσταση	Σημασία και τι να κάνετε
internal_error	500	Απρόσμενη αποτυχία. Επαναλάβετε μία φορά και μετά επικοινωνήστε με την υποστήριξη αναφέροντας το request_id.
upstream_unavailable	502	Η πύλη δεν μπόρεσε καθόλου να φτάσει στην υπηρεσία. Μια σύντομη επανάληψη συνήθως πετυχαίνει.
service_unavailable	503	Προγραμματισμένη συντήρηση ή ανοιχτός circuit breaker. Επαναλάβετε μετά την κεφαλίδα Retry-After.
ai_vendor_out_of_funds	503	Ο πάροχος AI σας απέρριψε την κλήση για λόγους χρέωσης (ένα 402 ή ένα 429 ορίου χρήσης από τον πάροχο). Ανανεώστε το υπόλοιπο στον λογαριασμό του παρόχου· μια επανάληψη δεν θα βοηθήσει.
upstream_timeout	504	Η υπηρεσία δεν απάντησε εγκαίρως. Επαναλάβετε όταν υπάρχει το retry_after.

Επαναλήψεις

Επαναλάβετε τα 429, 502, 503, 504 και τις αποτυχίες δικτύου με εκθετική καθυστέρηση και στείλτε το ίδιο Idempotency-Key στην επανάληψη, ώστε μια εγγραφή να μην εφαρμοστεί ποτέ δύο φορές. Μην επαναλαμβάνετε 4xx εκτός από το 429.