Όρια – Τεκμηρίωση

Αιτήματα ανά λεπτό

Κάθε endpoint επιτρέπει έναν σταθερό αριθμό αιτημάτων ανά λεπτό. Για τα endpoints δεδομένων και την ανάγνωση του λογαριασμού, όλα τα κλειδιά και τα tokens ενός λογαριασμού μετρούν μαζί. Κάθε αίτημα μετράει, ακόμη και ένα που απορρίφθηκε.

Endpoint
Endpoint	Τι	Όριο ανά λεπτό
fetch-organization	Προφίλ εταιρείας	60
fetch-person	Προφίλ προσώπου	60
search-organizations	Αναζήτηση & Εξαγωγή	60
fetch-document	Έγγραφα	5
signals	Signals	60
account	Ανάγνωση του λογαριασμού	30
account, auth/tokens	Διαχείριση bearer tokens· δημιουργία, ενημέρωση και διαγραφή κλειδιών, monitors και endpoints webhook	10
account/webhook-endpoints	Επαλήθευση και δοκιμή ενός endpoint webhook, εναλλαγή του secret	6

Η αναζήτηση, τα έγγραφα και τα Signals μοιράζονται ένα όριο 60 αιτημάτων ανά λεπτό. Τα έγγραφα έχουν επιπλέον δικό τους, μικρότερο όριο.

Τα αιτήματα εγγραφής στον λογαριασμό, στο Monitoring και στα webhooks μετρούν επίσης στο όριο του λογαριασμού. Οι ίδιοι αριθμοί αναφέρονται στο «Κόστος και όρια» σε κάθε σελίδα endpoint.

Τα όρια είναι ίδια σε κάθε συνδρομή πιστώσεων. Αν χρειάζεσαι περισσότερα αιτήματα ανά λεπτό, ένα συμβόλαιο Enterprise μπορεί να σου δώσει υψηλότερα όρια.

Το όριο εξαντλήθηκε

Πάνω από το όριο, το API απαντά με 429. Το header Retry-After σού λέει μετά από πόσα δευτερόλεπτα μπορείς να στείλεις ξανά αιτήματα. Ο ίδιος αριθμός βρίσκεται στο πεδίο retry_after.

Κάθε απάντηση δείχνει σε headers πόσο περιθώριο σου απομένει:

Header
Header	Σημασία	Παράδειγμα
X-RateLimit-Limit	Το όριο ανά λεπτό αυτού του endpoint.	`30`
X-RateLimit-Remaining	Πόσα ακόμη αιτήματα είναι δυνατά σε αυτό το λεπτό.	`0`
Retry-After	Μόνο με `429`: δευτερόλεπτα έως το επόμενο δυνατό αίτημα.	`17`
X-RateLimit-Reset	Μόνο με `429`: η στιγμή που μπορείς να συνεχίσεις, ως Unix time.	`1793519682`

1{2  "error": "Too many requests",3  "message": "Rate limit exceeded. Retry after 17 seconds.",4  "retry_after": 175}

429 · Παράδειγμα απάντησης πάνω από το όριο

Όταν στέλνεις πολλά αιτήματα, παρακολούθησε το X-RateLimit-Remaining και επιβράδυνε μόνος σου πριν το API απαντήσει με 429. Ένα αίτημα πάνω από το όριο δεν κοστίζει τίποτα.

Χρονικά όρια

Οι περισσότερες απαντήσεις φτάνουν μέσα σε λίγα δευτερόλεπτα. Η Λειτουργία AI, το feature news, οι ανακτήσεις πραγματικού χρόνου, το fetch-person και τα έγγραφα διαρκούν περισσότερο, γιατί ανακτούμε έγγραφα και δεδομένα πραγματικού χρόνου απευθείας από το μητρώο.

Όρισε το timeout του client σου σε τουλάχιστον 120 δευτερόλεπτα, ειδικά για Πραγματικό χρόνο, fetch-person και έγγραφα. Ένα πολύ σύντομο timeout ακυρώνει αιτήματα που είναι έτοιμα να ολοκληρωθούν.

Για τα έγγραφα υπάρχει επίσης το async=true: το API απαντά αμέσως με 202 και ανακτά το έγγραφο στο παρασκήνιο, βλ. fetch-document.

Αν η πηγή δεδομένων δεν απαντήσει εγκαίρως, λαμβάνεις 408, για έγγραφα 504 με Retry-After. Δεν χρεώνεται τίποτα. Επανάλαβε το αίτημα λίγο αργότερα. Αν αποτύχει μόνο η ζωντανή ανάκτηση για τον Πραγματικό χρόνο, λαμβάνεις το προφίλ εταιρείας με τα αποθηκευμένα δεδομένα, χωρίς την προσαύξηση Πραγματικού χρόνου.

Επανάληψη χωρίς διπλή χρέωση

Αν ο client σου ακυρώσει ένα αίτημα, αυτό μπορεί να ολοκληρωθεί στη δική μας πλευρά και να χρεωθεί. Με το header Idempotency-Key, η επανάληψη τότε δεν κοστίζει τίποτα.

Επίλεξε ξεχωριστό κλειδί για κάθε αίτημα και στείλε το αμετάβλητο με την επανάληψη. Ένα κλειδί έχει 1 έως 128 χαρακτήρες: γράμματα, ψηφία, τελεία, κάτω παύλα, άνω και κάτω τελεία και παύλα, και ξεκινά με γράμμα ή ψηφίο.

Ένα αίτημα με idempotency key

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: hetzner-profile-2026-11-01" \
  --data-urlencode "q=Ansbach HRB 6089"

Περίπτωση
Περίπτωση	Endpoints δεδομένων	Monitoring και webhooks
Απαιτείται κλειδί	όχι, προαιρετικό	ναι, διαφορετικά `428`
Παράθυρο	24 ώρες	24 ώρες
Ίδιο κλειδί, ίδιες παράμετροι	Ξανά το αποτέλεσμα, χωρίς χρέωση	Αποθηκευμένη απάντηση με το status της
Ίδιο κλειδί, διαφορετικές παράμετροι	`422` idempotency_key_reused	`409` idempotency_conflict
Μετά από σφάλμα	Το κλειδί μένει ελεύθερο	Επιστρέφει το ίδιο σφάλμα, χρειάζεται νέο κλειδί

Endpoints δεδομένων

Τα fetch-organization, fetch-person, search-organizations και fetch-document δέχονται το κλειδί προαιρετικά. Αν επαναλάβεις ένα αίτημα με το ίδιο κλειδί και τις ίδιες παραμέτρους μέσα σε 24 ώρες, λαμβάνεις ξανά το αποτέλεσμα, χωρίς χρέωση.

Η πρώτη απάντηση φέρει το header Idempotency-Status: created, κάθε επανάληψη Idempotency-Status: replayed και meta.request_credit_cost: 0. Μια επανάληψη δεν χρειάζεται υπόλοιπο.

Μόνο ένα αποτέλεσμα που παραδόθηκε δεσμεύει το κλειδί. Έτσι μετά από σφάλμα μπορείς να συνεχίσεις να χρησιμοποιείς το ίδιο κλειδί. Το ίδιο κλειδί με διαφορετικές παραμέτρους δίνει 422 με idempotency_key_reused. Τα endpoints δεδομένων αγνοούν ένα κλειδί σε διαφορετική μορφή, οπότε τήρησε ακριβώς τη μορφή. Το signals δεν δέχεται idempotency key.

1{2  "error": "idempotency_key_reused",3  "message": "This Idempotency-Key was already used with different parameters.",4  "meta": {5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}

422 · Παράδειγμα απάντησης: το ίδιο κλειδί με διαφορετικές παραμέτρους

Monitoring και webhooks

Τα αιτήματα εγγραφής προς /v1/account/monitors, /v1/account/webhook-endpoints και /v1/account/webhook-deliveries χρειάζονται το κλειδί. Χωρίς αυτό, το API απαντά με 428· ένα κλειδί σε λάθος μορφή δίνει 400.

Μέσα σε 24 ώρες, το ίδιο κλειδί με τις ίδιες παραμέτρους επιστρέφει την αποθηκευμένη απάντηση με το status της, καθώς και Idempotency-Status: replayed. Αυτό ισχύει και για σφάλματα. Για μια νέα προσπάθεια, όπως μια νέα επαλήθευση, χρησιμοποιείς επομένως νέο κλειδί.

Το ίδιο κλειδί με διαφορετικές παραμέτρους δίνει 409 με idempotency_conflict. Αν το πρώτο αίτημα εκτελείται ακόμη, λαμβάνεις 409 με idempotency_in_progress.

Σχεδιασμός επαναλήψεων

Δεν αξίζει κάθε σφάλμα μια δεύτερη προσπάθεια. Έτσι προχωράς:

Επανάληψη: 408, 429 μετά το Retry-After και 5xx. Περίμενε κάθε φορά περισσότερο μεταξύ των προσπαθειών, για παράδειγμα 2, 4 και 8 δευτερόλεπτα, και σταμάτα μετά από λίγες προσπάθειες.
Πρώτα διόρθωση, μετά νέα αποστολή: 400, 401, 402, 403, 404 και 422. Η ίδια αποστολή ξανά φέρνει το ίδιο αποτέλεσμα.
Στείλε ένα idempotency key με τα αιτήματα επί πληρωμή. Τότε μια επανάληψη μετά από ακύρωση δεν κοστίζει τίποτα.