Feil

Sursa bruker HTTP-statuskoder for å si om en forespørsel lyktes, og en stabil feilkode for å si hvorfor den ikke gjorde det. Alle feilsvar har samme form:

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

Felt	Betydning
`error.code`	Stabil kode på formen `<area>.<reason>`. La koden din forgrene seg etter den.
`error.message`	En lesbar forklaring på engelsk. Den kan omformuleres når som helst; ikke tolk den.
`error.details`	Strukturerte fakta om feilen, for eksempel parameteren, en grense eller når du kan prøve på nytt. Feltene avhenger av koden.
`error.request_id`	ID-en til denne forespørselen, den samme som i headeren `X-Request-Id` i svaret.
`error.doc_url`	Siden om denne koden i denne portalen.
`detail`	Den tidligere formen på feilen, beholdt for eksisterende integrasjoner. Ny kode bør lese `error`.

Hver kode har sin egen side under Feilkoder, med HTTP-statusen, feltene i details og operasjonene som returnerer den. Siden for hver operasjon i API-referansen viser kodene som operasjonen kan returnere.

HTTP-statuser

Status	Betydning
`200`, `201`, `202`, `204`	Forespørselen lyktes. `202` betyr at den er tatt imot og fortsatt behandles.
`400`	Forespørselen er feilformet: en ugyldig parameter, cursor, `metadata` eller `Idempotency-Key`. Rett forespørselen.
`401`	Ingen gyldig nøkkel. Se Autentisering.
`402`	En grense i organisasjonens prisplan er nådd, for eksempel antall kort eller lagringsplass.
`403`	Nøkkelen er gyldig, men har ikke lov til å gjøre dette: En rolle, et scope eller en funksjon i prisplanen mangler.
`404`	Objektet finnes ikke, eller nøkkelen har ikke lov til å se det.
`409`	Forespørselen er i konflikt med den nåværende tilstanden: en duplisert `external_id`, en åpen synkronisering, en forespørsel med samme `Idempotency-Key` som fortsatt kjører.
`410`	Objektet er utløpt, for eksempel en opplasting etter 24 timer, eller ruten er faset ut.
`413`	Brødteksten eller filen er for stor.
`415`	Filtypen støttes ikke, eller innholdet stemmer ikke med navnet.
`422`	Forespørselen er riktig formet, men ugyldig: et manglende felt eller en verdi utenfor tillatt område.
`429`	For mange forespørsler, eller en kvote er brukt opp. Se Hastighetsgrenser og kvoter.
`500`, `502`, `503`, `504`	Et problem hos Sursa. Prøv på nytt senere.

Valideringsfeil

For 422 med koden validation.failed viser detail alle felt som ikke besto valideringen, hvert med sin plassering:

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

Hvilke feil du bør prøve på nytt

Feil	Prøve på nytt?
Nettverksfeil eller tidsavbrudd, ingen svar	Ja, med den samme `Idempotency-Key`.
`429`	Ja, etter så mange sekunder som `Retry-After` angir.
`500`, `502`, `503`, `504`	Ja, med eksponentiell backoff: 1 s, 2 s, 4 s og så videre opptil ett minutt, med tilfeldig jitter.
`409` `api.idempotency_in_progress`	Ja, etter `Retry-After`: Den første forespørselen med denne nøkkelen kjører fortsatt.
Alle andre `4xx`	Nei. Den samme forespørselen vil mislykkes igjen; rett den først.

Prøv POST- og PATCH-forespørsler på nytt bare med en Idempotency-Key, slik at et nytt forsøk etter et tapt svar ikke kan opprette et objekt til. GET, PUT og DELETE er trygge å prøve på nytt som de er.

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

Melde fra om et problem

Hvert svar, vellykket eller ikke, har en X-Request-Id-header, og hver feil har den samme verdien i error.request_id. Logg den sammen med din egen registrering av forespørselen. Når du kontakter brukerstøtten om en forespørsel, sender du ID-en til forespørselen: Den fører rett til registreringen av akkurat den forespørselen.

Håndtere koder du ikke kjenner

Nye feilkoder kan dukke opp i hvilken som helst versjon av API-et. Behandle en ukjent kode etter HTTP-statusen: en ukjent 4xx som en forespørsel som ikke vil lykkes slik den er, en ukjent 5xx som et midlertidig problem.