Fouten

Sursa gebruikt HTTP-statuscodes om aan te geven of een request is geslaagd, en een stabiele foutcode om aan te geven waarom niet. Elke foutresponse heeft dezelfde vorm:

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

Elke code heeft een eigen pagina onder Foutcodes, met de HTTP-status, de velden van details en de endpoints die de code teruggeven. Op de pagina van elk endpoint in de API-referentie staan de codes die dat endpoint kan teruggeven.

HTTP-statussen

Validatiefouten

Bij 422 met de code validation.failed somt detail elk veld op dat niet door de validatie kwam, elk met zijn locatie:

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

Welke fouten je opnieuw probeert

Probeer POST- en PATCH-requests alleen opnieuw met een Idempotency-Key, zodat een nieuwe poging na een verloren response geen tweede object kan maken. GET, PUT en DELETE kun je zonder meer opnieuw proberen.

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

Een probleem melden

Elke response, geslaagd of niet, heeft een header X-Request-Id, en elke fout heeft dezelfde waarde in error.request_id. Log die samen met je eigen gegevens over het request. Neem je over een request contact op met de support, stuur dan de request-ID mee: daarmee is het record van dat request direct te vinden.

Omgaan met codes die je niet kent

Er kunnen in elke versie van de API nieuwe foutcodes verschijnen. Behandel een onbekende code op basis van zijn HTTP-status: een onbekende 4xx als een request dat in deze vorm niet zal slagen, een onbekende 5xx als een tijdelijk probleem.