الأخطاء

يستخدم 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

أخطاء صحة البيانات

في الحالة 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…"}
}

الأخطاء التي تُعاد المحاولة عندها

لا تُعِد محاولة طلبات 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. سجّلها مع سجلك الخاص للطلب. وحين تتواصل مع الدعم بشأن طلب، أرسل معرّف الطلب: فهو يقود مباشرة إلى سجل ذلك الطلب.

التعامل مع الرموز المجهولة

قد تظهر رموز أخطاء جديدة في أي إصدار من واجهة API. تعامل مع الرمز المجهول حسب حالة HTTP: الحالة 4xx المجهولة طلب لن ينجح كما هو، والحالة 5xx المجهولة مشكلة مؤقتة.