एरर

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"
  }
}

हर कोड का एरर कोड में अपना पेज है, जिसमें उसका HTTP स्टेटस, details के फ़ील्ड और उसे लौटाने वाले एंडपॉइंट दिए गए हैं। API रेफ़रेंस में हर एंडपॉइंट के पेज पर वे कोड दिए गए हैं, जो वह एंडपॉइंट लौटा सकता है।

HTTP स्टेटस

वैलिडेशन एरर

कोड validation.failed वाले 422 में 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…"}
}

किन एरर पर रीट्राई करें

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 को अस्थायी समस्या।