Lỗi

Sursa dùng mã trạng thái HTTP để cho biết yêu cầu có thành công hay không, và một mã lỗi ổn định để cho biết vì sao không thành công. Mọi phản hồi lỗi có cùng một cấu trúc:

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

Mỗi mã có trang riêng trong Mã lỗi, với trạng thái HTTP, các trường của details và các endpoint trả về nó. Trang của mỗi endpoint trong tài liệu tham chiếu API liệt kê các mã mà endpoint đó có thể trả về.

Trạng thái HTTP

Lỗi dữ liệu không hợp lệ

Với 422 và mã validation.failed, detail liệt kê mọi trường không hợp lệ, mỗi trường kèm vị trí của nó:

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

Lỗi nào nên thử lại

Chỉ thử lại yêu cầu POST và PATCH khi có Idempotency-Key, để lần thử lại sau khi mất phản hồi không thể tạo ra đối tượng thứ hai. GET, PUT và DELETE có thể thử lại nguyên trạng một cách an toàn.

// 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." }),
  }),
);

Báo cáo sự cố

Mọi phản hồi, thành công hay không, đều có header X-Request-Id, và mọi lỗi có cùng giá trị đó trong error.request_id. Hãy ghi nó vào nhật ký cùng bản ghi của bạn về yêu cầu. Khi liên hệ bộ phận hỗ trợ về một yêu cầu, hãy gửi ID yêu cầu của nó: ID này dẫn thẳng tới bản ghi của yêu cầu đó.

Xử lý các mã bạn không biết

Mã lỗi mới có thể xuất hiện trong bất kỳ phiên bản nào của API. Hãy xử lý mã không xác định theo trạng thái HTTP của nó: một 4xx không xác định là yêu cầu sẽ không thành công nếu giữ nguyên, một 5xx không xác định là sự cố tạm thời.