Σφάλματα + όρια ρυθμού

Ένας φάκελος σφάλματος σε κάθε endpoint. Τυπικοί κωδικοί HTTP status + μια δομημένη συμβολοσειρά code για προγραμματιστική αντιστοίχιση. Κεφαλίδες ορίου ρυθμού σε κάθε απόκριση ώστε να ρυθμίζετε τον ρυθμό σας πριν φτάσετε σε 429.

Φάκελος σφάλματος

{
  "detail": "Human-readable summary.",
  "code": "billing.subscription_past_due",
  "field_errors": {
    "scheduled_for": ["Must be a future ISO 8601 timestamp."]
  }
}

detail — πάντα παρόν, ασφαλές για απόδοση σε ανθρώπους (μεταφράζεται όπου είναι διαθέσιμο το locale).
code — παρόν για διακριτές καταστάσεις σφάλματος. Σταθερό μεταξύ εκδόσεων API· αντιστοιχίστε σε αυτό για τη λογική επανάληψης.
field_errors — παρόν μόνο σε αποτυχίες επικύρωσης 400. Χάρτης όνομα-πεδίου → λίστα μηνυμάτων.

Μήτρα κωδικών status

Status	Κλάση	Επανάληψη;	Συνήθεις αιτίες
400	Επικύρωση	Όχι	Λείπει υποχρεωτικό πεδίο, κακή μορφή, παραβίαση επιχειρησιακού κανόνα
401	Auth	Όχι	Λείπει / κακό / ανακληθέν διαπιστευτήριο
402	Χρέωση	Όχι	Ληξιπρόθεσμη συνδρομή, εξάντληση ορίου δωρεάν πλάνου
403	Δικαίωμα	Όχι	Το διαπιστευτήριο δεν έχει scope, ή ο πόρος βρίσκεται σε διαφορετικό org
404	Δεν βρέθηκε	Όχι	Ο πόρος δεν υπάρχει ή δεν είναι ορατός στο διαπιστευτήριό σας
409	Σύγκρουση	Ενίοτε	Αναντιστοιχία επαναχρησιμοποίησης Idempotency-Key, παραβίαση μηχανής καταστάσεων
422	Μη επεξεργάσιμο	Όχι	Σημασιολογικά μη έγκυρος συνδυασμός έγκυρων πεδίων
429	Περιορισμός ρυθμού	Ναι, με backoff	Ενεργοποιήθηκε ο περιορισμός ανά διαπιστευτήριο ή ανά οργανισμό
500	Σφάλμα διακομιστή	Ναι, με backoff	Απροσδόκητο — ανοίξτε αίτημα υποστήριξης αν επιμένει
502 / 503 / 504	Παροδικό	Ναι, με backoff	Upstream / deploy / φόρτος

Αξιοσημείωτοι κωδικοί σφαλμάτων

Κωδικός	Κατάσταση	Τι σημαίνει
`billing.subscription_past_due`	402	Η συνδρομή Stripe του οργανισμού είναι ληξιπρόθεσμη. Κατευθύνετε τον διαχειριστή στο `/admin/billing`.
`billing.free_plan_minutes_exhausted`	402	Η βαθμίδα Free / Pilot έχει εξαντλήσει τις 5 επιθεωρήσεις της.
`billing.signature_pack_exhausted`	402	Οι πιστώσεις του πακέτου υπογραφών εξαντλήθηκαν· χρησιμοποιήστε χρέωση ανά υπογραφή ή αγοράστε νέο πακέτο.
`permission_denied`	403	Το διαπιστευτήριο δεν διαθέτει το scope. Δείτε το `field_errors.required_scope`.
`idempotency.key_mismatch`	409	Ίδιο key, διαφορετικό σώμα. Χρησιμοποιήστε νέο key.
`session.already_ended`	409	Κλήση του `end` σε μη ανοιχτή συνεδρία (συνήθως ασφαλές — το `end` είναι idempotent, αφορά τις ακραίες περιπτώσεις).
`kyb.not_verified`	403	Ζητήθηκε υπογραφή QES σε οργανισμό που δεν έχει ολοκληρώσει τον έλεγχο KYB.
`rate_limited`	429	Ενεργοποιήθηκε ο περιορισμός ανά διαπιστευτήριο (60 rpm) ή ανά οργανισμό (600 rpm).

Κεφαλίδες περιορισμού ρυθμού

Κάθε απόκριση — επιτυχία ή σφάλμα — μεταφέρει την κατάσταση περιορισμού:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1716461235

X-RateLimit-Limit — το όριο που ισχύει για αυτό το αίτημα.
X-RateLimit-Remaining — πόσες κλήσεις απομένουν στο τρέχον παράθυρο.
X-RateLimit-Reset — χρονοσήμανση Unix κατά την οποία μηδενίζεται το Remaining.

Σε 429, ορίζεται επίσης το Retry-After (σε δευτερόλεπτα) σύμφωνα με το RFC 6585.

Πεδία εφαρμογής περιορισμού

Scope	Όριο	Παράθυρο
Ανά διαπιστευτήριο	60	1 λεπτό
Ανά οργανισμό (σε όλα τα διαπιστευτήρια)	600	1 λεπτό

Επιτρέπει ριπές για το πρώτο δευτερόλεπτο του λεπτού. Με το που φτάσετε το όριο, τα επόμενα αιτήματα εντός του παραθύρου επιστρέφουν 429.

Στρατηγική επανάληψης

Εκθετική υποχώρηση με jitter για 429 / 5xx· μην επαναλαμβάνετε τα 4xx (εκτός από 408, 425, 429):

async function withRetry<T>(fn: () => Promise<T>, max = 5): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < max; i++) {
    try {
      return await fn();
    } catch (err: any) {
      const status = err?.status;
      if (status >= 400 && status < 500 && ![408, 425, 429].includes(status)) {
        throw err; // not retryable
      }
      const base = status === 429 ? (err.retryAfterMs ?? 1000) : 250 * 2 ** i;
      const jitter = Math.random() * base * 0.2;
      await new Promise((r) => setTimeout(r, base + jitter));
      lastErr = err;
    }
  }
  throw lastErr;
}

Τα SDK το υλοποιούν εσωτερικά σε 429 + 5xx· αν προτιμάτε να χειρίζεστε τις επαναλήψεις μόνοι σας, ορίστε retries: 0 στις επιλογές του SDK.

Συσχέτιση σφαλμάτων

Κάθε απόκριση μεταφέρει μια κεφαλίδα X-Request-Id (UUID). Αναφέρετέ την σε οποιοδήποτε αίτημα υποστήριξης — μπορούμε να ανακτήσουμε το πλήρες ίχνος του αιτήματος μόνο από αυτό το id.

Τι ακολουθεί

Έλεγχος ταυτότητας — εναλλαγή διαπιστευτηρίων αν βλέπετε 401
Σελιδοποίηση + idempotency — τα μοτίβα που αλληλεπιδρούν με τις επαναλήψεις