Σφάλματα

Η Sursa χρησιμοποιεί κωδικούς κατάστασης HTTP για να δείξει αν ένα αίτημα πέτυχε και έναν σταθερό κωδικό σφάλματος για να δείξει γιατί δεν πέτυχε. Κάθε απόκριση σφάλματος έχει την ίδια μορφή:

{
  "detail": "the cursor is malformed or was issued for different filters",
  "error": {
    "code": "api.cursor_invalid",
    "message": "the cursor is malformed or was issued for different filters",
    "details": {"parameter": "cursor"},
    "request_id": "01JB7Q2M4X9V3K8T5N6P0R1S2A",
    "doc_url": "https://developers.sursa.com/errors/api.cursor_invalid"
  }
}

Πεδίο	Σημασία
`error.code`	Σταθερός κωδικός της μορφής `<area>.<reason>`. Βασίστε τη λογική του κώδικά σας σε αυτόν.
`error.message`	Αναγνώσιμη εξήγηση στα αγγλικά. Η διατύπωσή της μπορεί να αλλάξει ανά πάσα στιγμή· μην την αναλύετε.
`error.details`	Δομημένα στοιχεία για το σφάλμα, όπως η παράμετρος, ένα όριο ή πότε να επαναλάβετε το αίτημα. Τα πεδία του εξαρτώνται από τον κωδικό.
`error.request_id`	Το ID αυτού του αιτήματος, ίδιο με την κεφαλίδα απόκρισης `X-Request-Id`.
`error.doc_url`	Η σελίδα για αυτόν τον κωδικό σε αυτή την πύλη.
`detail`	Η παλαιότερη μορφή του σφάλματος, που διατηρείται για τις υπάρχουσες ενσωματώσεις. Ο νέος κώδικας πρέπει να διαβάζει το `error`.

Κάθε κωδικός έχει τη δική του σελίδα στους Κωδικούς σφαλμάτων, με την κατάσταση HTTP, τα πεδία του details και τα τελικά σημεία που τον επιστρέφουν. Η σελίδα κάθε τελικού σημείου στην αναφορά API απαριθμεί τους κωδικούς που μπορεί να επιστρέψει αυτό το τελικό σημείο.

Καταστάσεις HTTP

Κατάσταση	Σημασία
`200`, `201`, `202`, `204`	Το αίτημα πέτυχε. Το `202` σημαίνει ότι το αίτημα έγινε δεκτό και η επεξεργασία του συνεχίζεται.
`400`	Το αίτημα είναι κακοσχηματισμένο: λάθος παράμετρος, δρομέας, `metadata` ή `Idempotency-Key`. Διορθώστε το αίτημα.
`401`	Δεν υπάρχει έγκυρο κλειδί. Δείτε τον οδηγό Έλεγχος ταυτότητας.
`402`	Έχει εξαντληθεί ένα όριο του πακέτου του οργανισμού, όπως ο αριθμός των καρτών ή ο χώρος αποθήκευσης.
`403`	Το κλειδί είναι έγκυρο, αλλά δεν επιτρέπεται να κάνει αυτή την ενέργεια: λείπει ένας ρόλος, μια εμβέλεια ή μια δυνατότητα του πακέτου.
`404`	Το αντικείμενο δεν υπάρχει ή το κλειδί δεν επιτρέπεται να το δει.
`409`	Το αίτημα συγκρούεται με την τρέχουσα κατάσταση: διπλότυπο `external_id`, ανοιχτός συγχρονισμός, αίτημα με το ίδιο `Idempotency-Key` που εκτελείται ακόμη.
`410`	Το αντικείμενο έχει λήξει, όπως μια μεταφόρτωση μετά από 24 ώρες, ή η διαδρομή έχει αποσυρθεί.
`413`	Το σώμα ή το αρχείο είναι πολύ μεγάλο.
`415`	Ο τύπος αρχείου δεν υποστηρίζεται ή το περιεχόμενό του δεν αντιστοιχεί στο όνομά του.
`422`	Το αίτημα είναι σωστά σχηματισμένο, αλλά μη έγκυρο: λείπει ένα πεδίο ή μια τιμή είναι εκτός εύρους.
`429`	Υπερβολικά πολλά αιτήματα ή εξαντλημένη ποσόστωση. Δείτε τον οδηγό Όρια ρυθμού και ποσοστώσεις.
`500`, `502`, `503`, `504`	Πρόβλημα από την πλευρά της Sursa. Επαναλάβετε αργότερα.

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

Για το 422 με τον κωδικό validation.failed, το detail απαριθμεί κάθε πεδίο που απέτυχε, το καθένα με τη θέση του:

{
  "detail": [
    {"loc": ["body", "title"], "msg": "String should have at least 1 character", "type": "string_too_short"}
  ],
  "error": {"code": "validation.failed", "message": "request validation failed", "request_id": "01JB7…"}
}

Ποια σφάλματα αξίζει να επαναλάβετε

Σφάλμα	Επανάληψη;
Σφάλμα δικτύου ή λήξη χρονικού ορίου, καμία απόκριση	Ναι, με το ίδιο `Idempotency-Key`.
`429`	Ναι, μετά από τον αριθμό δευτερολέπτων στο `Retry-After`.
`500`, `502`, `503`, `504`	Ναι, με εκθετική αύξηση της αναμονής: 1 s, 2 s, 4 s… έως ένα λεπτό, με τυχαία διακύμανση (jitter).
`409` `api.idempotency_in_progress`	Ναι, μετά το `Retry-After`: το πρώτο αίτημα με αυτό το κλειδί εκτελείται ακόμη.
Οποιοδήποτε άλλο `4xx`	Όχι. Το ίδιο αίτημα θα αποτύχει ξανά· διορθώστε το πρώτα.

Επαναλαμβάνετε τα αιτήματα POST και PATCH μόνο με Idempotency-Key, ώστε μια επανάληψη μετά από μια απόκριση που χάθηκε να μην μπορεί να δημιουργήσει δεύτερο αντικείμενο. Τα GET, PUT και DELETE μπορούν να επαναληφθούν με ασφάλεια όπως είναι.

// Retries a request on network errors, 429 and 5xx. The same Idempotency-Key is sent on every attempt.
async function withRetries(send, attempts = 5) {
  for (let attempt = 1; ; attempt++) {
    let response;
    try {
      response = await send();
    } catch (error) {
      if (attempt >= attempts) throw error;
    }
    if (response && response.status !== 429 && response.status < 500) return response;
    if (attempt >= attempts) return response;
    const retryAfter = Number(response?.headers.get("Retry-After"));
    const backoff = Math.min(60, 2 ** (attempt - 1)) * (0.8 + Math.random() * 0.4);
    await new Promise((resolve) => setTimeout(resolve, 1000 * (retryAfter || backoff)));
  }
}

const key = crypto.randomUUID();
const response = await withRetries(() =>
  fetch("https://api.sursa.com/v1/cards/text", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SURSA_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify({ title: "Refund policy", body_markdown: "Refunds take 14 days." }),
  }),
);

Αναφορά προβλήματος

Κάθε απόκριση, επιτυχής ή όχι, έχει μια κεφαλίδα X-Request-Id, και κάθε σφάλμα έχει την ίδια τιμή στο error.request_id. Καταγράψτε το μαζί με τη δική σας εγγραφή για το αίτημα. Όταν επικοινωνείτε με την υποστήριξη για ένα αίτημα, στείλτε το ID του αιτήματος: οδηγεί κατευθείαν στην εγγραφή αυτού του αιτήματος.

Χειρισμός άγνωστων κωδικών

Νέοι κωδικοί σφάλματος μπορεί να εμφανιστούν σε οποιαδήποτε έκδοση του API. Χειριστείτε έναν άγνωστο κωδικό με βάση την κατάσταση HTTP του: ένα άγνωστο 4xx ως αίτημα που δεν θα πετύχει όπως είναι, ένα άγνωστο 5xx ως προσωρινό πρόβλημα.