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

Το σώμα σφάλματος#

{
  "error": {
    "code": "NOTFOUND",
    "message": "Entry not found",
    "requestId": "0f6c1d2e-3b4a-4c5d-8e9f-a0b1c2d3e4f5"
  }
}

Το GraphQL αναφέρει τα σφάλματα ερωτημάτων στον δικό του πίνακα errors· δείτε σφάλματα GraphQL.

Αναγνωριστικά αιτημάτων#

Κάθε σφάλμα περιέχει requestId, όπως και το meta.requestId στις επιτυχείς απαντήσεις επικοινωνίας και κρατήσεων. Στείλτε τη δική σας κεφαλίδα X-Request-Id και το API θα τη χρησιμοποιήσει, ώστε να αντιστοιχίζετε τα δικά σας αρχεία καταγραφής με τα δικά μας. Συμπεριλάβετέ το κάθε φορά που επικοινωνείτε με την υποστήριξη.

# Send your own id and it comes back as requestId (and in the API's logs)
curl https://api.console.citronos.com/v1/content/nope \
  -H "Authorization: Bearer $CITRON_API_KEY" \
  -H "X-Request-Id: my-site-7f3a"
# {"error":{"code":"NOTFOUND","message":"Collection \"nope\" not found","requestId":"my-site-7f3a"}}

Κωδικοί κατάστασης#

Κωδικοί σφάλματος#

Τα περισσότερα σφάλματα χρησιμοποιούν έναν γενικό κωδικό που προκύπτει από την κατάσταση. Ορισμένα endpoints προσθέτουν έναν πιο συγκεκριμένο. Συγκρίνετε τους κωδικούς ακριβώς όπως είναι γραμμένοι: οι γενικοί δεν έχουν κάτω παύλα.

Σφάλματα επικύρωσης#

Οι φόρμες εξηγούν κάθε πεδίο:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Please check the highlighted fields",
    "details": [{ "field": "email", "message": "Enter a valid email" }],
    "requestId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
  }
}

Τα endpoints επικοινωνίας και κρατήσεων επικυρώνουν αυστηρά το σώμα JSON και απαριθμούν κάθε πρόβλημα, συμπεριλαμβανομένων των πεδίων που δεν δέχονται:

{
  "error": {
    "code": "BADREQUEST",
    "message": ["mode must be one of the following values: online, in_office"],
    "details": ["mode must be one of the following values: online, in_office"],
    "requestId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
  }
}

Όρια ρυθμού#

• Όταν ξεπεραστεί ένα όριο, η απάντηση είναι 429. Τα όρια ανά IP προσθέτουν Retry-After-short (το παράθυρο του λεπτού) ή Retry-After-long (το παράθυρο της ώρας) με τα δευτερόλεπτα αναμονής. Το όριο ανά κλειδί μηδενίζεται στην αρχή του επόμενου λεπτού.
• Ο διακομιστής του ιστοτόπου σας συνήθως ανακτά περιεχόμενο από μία IP· το API περιεχομένου περιορίζεται ανά κλειδί και όχι ανά IP, οπότε η απόδοση των σελίδων δεν επιβραδύνεται ποτέ από τους επισκέπτες.
• Αν προωθείτε τις υποβολές μέσω του διακομιστή σας, μεταβιβάστε το x-forwarded-for ώστε κάθε επισκέπτης να έχει το δικό του όριο.
• Χρησιμοποιήστε κρυφή μνήμη από την πλευρά σας (ETags, επανεπικύρωση Next.js, webhooks) αντί να ανακτάτε περιεχόμενο σε κάθε προβολή σελίδας.

Στο SDK#

Το SDK μετατρέπει κάθε σώμα σφάλματος σε CitronError και επαναλαμβάνει αυτόματα τα αιτήματα σε 429 και 5xx. Δείτε σφάλματα στο SDK.

import { CitronGraphQLError, isCitronError } from '@citron/sdk';

try {
  await citron.collection('products').get('does-not-exist');
} catch (err) {
  if (err instanceof CitronGraphQLError) {
    console.error(err.errors, err.data); // GraphQL errors and partial data
  } else if (isCitronError(err)) {
    console.error(err.status, err.code, err.message, err.requestId, err.details);
    if (err.isNotFound) { /* render your 404 */ }
    if (err.isRetryable) { /* 0, 408, 429 or 5xx; err.retryAfter when the server said */ }
  } else {
    throw err;
  }
}