Όρια ρυθμού και ποσοστώσεις

Δύο είδη ορίων κρατούν το API γρήγορο για όλους:

• Το όριο ρυθμού ενός κλειδιού: πόσα αιτήματα ανά δευτερόλεπτο μπορεί να στέλνει, με μια ριπή (burst) για σύντομες αιχμές.
• Οι ποσοστώσεις του οργανισμού: πόσα αιτήματα μπορούν να στείλουν όλα τα κλειδιά του μαζί ανά λεπτό, ανά ημέρα και ανά μήνα.

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

Όριο ρυθμού ενός κλειδιού

Κάθε κλειδί έχει έναν σταθερό ρυθμό και μια ριπή. Η ριπή σας επιτρέπει να στείλετε τόσα αιτήματα με μιας· μετά από αυτό, τα αιτήματα επιτρέπονται με τον σταθερό ρυθμό.

Η κατηγορία προκύπτει από το πακέτο του οργανισμού. Το GET /v1/me δείχνει την κατηγορία, τον ρυθμό και τη ριπή του κλειδιού που το καλεί (rate_limit). Το όριο ισχύει για το κλειδί συνολικά, όσοι διακομιστές του API κι αν εξυπηρετούν τα αιτήματά σας.

Τα τελικά σημεία ροής, το POST /v1/chat (με ή χωρίς "stream": true) και το GET /v1/jobs/stream, βρίσκονται εκτός του ορίου ρυθμού του κλειδιού: δεν το καταναλώνουν και οι κεφαλίδες RateLimit τους δεν έχουν στοιχείο "key". Μετρούν όμως στις ποσοστώσεις του οργανισμού, μία φορά το καθένα, όταν ξεκινά το αίτημα. Οι ερωτήσεις έχουν δικά τους όρια, που περιγράφονται παρακάτω.

Ποσοστώσεις του οργανισμού

Ένα πακέτο μπορεί να ορίζει ποσοστώσεις αιτημάτων για τον οργανισμό: ανά λεπτό, ανά ημέρα και ανά μήνα. Τα παράθυρα είναι ημερολογιακές περίοδοι σε UTC: ένα λεπτό αρχίζει στα :00 δευτερόλεπτα, μια ημέρα στις 00:00 UTC, ένας μήνας την πρώτη ημέρα στις 00:00 UTC. Μετρά κάθε αίτημα με ένα κλειδί ή ένα διακριτικό OAuth του οργανισμού, σε οποιαδήποτε διεύθυνση. Ένα αίτημα ροής μετρά μία φορά, όταν ξεκινά, όσο κι αν διαρκεί· όταν η ποσόστωση έχει εξαντληθεί, απορρίπτεται με 429 όπως κάθε άλλο αίτημα. Ένα αίτημα που απορρίφθηκε με 429 δεν μετρά.

Οι κεφαλίδες

Κάθε απόκριση σε αίτημα με κλειδί περιέχει τα όρια που ισχύουν γι’ αυτό:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

Τα RateLimit-Policy και RateLimit ακολουθούν το προσχέδιο της IETF RateLimit header fields for HTTP. Κάθε στοιχείο είναι ένα όριο:

Τα X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset αναφέρουν το αυστηρότερο από αυτά τα όρια σε απλούστερη μορφή, για πελάτες που γράφτηκαν πριν υπάρξει το RateLimit. Το X-RateLimit-Reset είναι σε δευτερόλεπτα.

Όταν εξαντλείται ένα όριο

Το API απαντά 429 Too Many Requests με μια κεφαλίδα Retry-After σε δευτερόλεπτα:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Περιμένετε όσο λέει το Retry-After και επαναλάβετε το αίτημα. Επαναλαμβάνετε τα POST και PATCH με το ίδιο Idempotency-Key. Οι βοηθητικές συναρτήσεις επανάληψης στον οδηγό Σφάλματα κάνουν και τα δύο.

Και άλλα όρια του πακέτου απαντούν 429 με Retry-After, για παράδειγμα ο αριθμός των ερωτήσεων ανά ημέρα (limits.questions) ή οι απαντήσεις που ετοιμάζονται ταυτόχρονα (limits.concurrent_answers). Χειριστείτε τα με τον ίδιο τρόπο.

Πώς μένετε εντός των ορίων

• Διαβάζετε το RateLimit και επιβραδύνετε όταν το r πέφτει χαμηλά, αντί να περιμένετε ένα 429.
• Κατανέμετε τις μαζικές εργασίες στον χρόνο και χρησιμοποιείτε τα τελικά σημεία παρτίδων όπου υπάρχουν: μια παρτίδα 100 εγγράφων είναι ένα αίτημα.
• Μην ελέγχετε για αλλαγές σε έναν σφιχτό βρόχο. Εγγραφείτε σε webhooks ή διαβάζετε την τροφοδοσία συμβάντων κάθε λίγα δευτερόλεπτα.
• Εκτελείτε παράλληλες διεργασίες με κοινό περιοριστή ρυθμού. Πολλές διεργασίες με ένα κλειδί μοιράζονται ένα όριο ρυθμού.
• Ρωτήστε τον υπεύθυνο επικοινωνίας σας στη Sursa για μια υψηλότερη κατηγορία, αν η ενσωμάτωσή σας χρειάζεται περισσότερα.