오류

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는 일시적인 문제로 처리하세요.