Erreurs

Sursa indique par le statut HTTP si une requête a réussi et, par un code d’erreur stable, pourquoi elle a échoué. Toutes les réponses d’erreur ont la même forme :

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

Chaque code a sa propre page dans Codes d’erreur, avec son statut HTTP, les champs de details et les points de terminaison qui le renvoient. La page de chaque point de terminaison dans la référence de l’API liste les codes que ce point de terminaison peut renvoyer.

Statuts HTTP

Erreurs de validation

Pour 422 avec le code validation.failed, detail liste chaque champ en erreur, avec son emplacement :

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

Erreurs à réessayer

Ne réessayez les requêtes POST et PATCH qu’avec une clé d’idempotence : ainsi, une nouvelle tentative après une réponse perdue ne peut pas créer un second objet. Les requêtes GET, PUT et DELETE peuvent être réessayées telles quelles sans risque.

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

Signaler un problème

Chaque réponse, réussie ou non, contient un en-tête X-Request-Id, et chaque erreur porte la même valeur dans error.request_id. Journalisez-le avec votre propre trace de la requête. Quand vous contactez le support au sujet d’une requête, transmettez son identifiant de requête : il mène directement à la trace de cette requête.

Traiter les codes inconnus

De nouveaux codes d’erreur peuvent apparaître dans n’importe quelle version de l’API. Traitez un code inconnu selon son statut HTTP : un 4xx inconnu comme une requête qui ne réussira pas telle quelle, un 5xx inconnu comme un problème temporaire.