Грешки

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. Записвайте я в дневника заедно със собствения си запис за заявката. Когато се свързвате с поддръжката относно заявка, изпратете нейното ID: то води направо до записа за тази заявка.

Обработка на непознати кодове

Нови кодове на грешки може да се появят във всяка версия на API. Обработвайте непознат код по HTTP статуса му: непознат 4xx – като заявка, която няма да успее в този вид, непознат 5xx – като временен проблем.