Errors de l'API

Com informa d'errors l'API de Feedjolt: codis HTTP, que reintentar amb backoff, la capcalera X-Request-ID per a informes, limits de tasa i errors de validacio.

L'API fa servir codis HTTP estàndard per als resultats. Els cossos de resposta d'error segueixen la forma per defecte de FastAPI (un camp detail amb un string o payload estructurat). Els detalls d'error per endpoint estan a la referència OpenAPI.

Codis d'estat HTTP

Codi	Significat	Reintentar?
200, 201, 204	Èxit.	n/a
400	Error de validació. Cos o query malament.	No - arregla la petició.
401	Auth absent/invàlida.	No - arregla l'auth.
403	Auth OK però li falten scope o permisos.	No - ajusta scopes.
404	Recurs no trobat, O no accessible per a la teva clau.	No - verifica l'ID.
409	Conflicte (per exemple, slug ja agafat).	A vegades - depèn de la causa.
410	Gone - el recurs va ser eliminat.	No.
422	Validació semàntica.	No - arregla la petició.
429	Rate limited.	Sí, amb backoff.
500	El nostre bug. Si us plau reporta.	Sí, amb backoff.
502, 503, 504	Problema d'infraestructura transitori.	Sí, amb backoff.

IDs de petició

Cada resposta de l'API inclou:

X-Request-ID: <uuid>

Quan reportis un bug, inclou l'ID de petició - ens permet tirar de la traça completa del servidor en segons en lloc d'endevinar des d'una descripció.

Hola, vaig rebre un 500 cridant POST /posts amb aquest cos: {...}
X-Request-ID: 7e6f2b71-...

404 vs. 403

Deliberadament no diferenciem entre "no existeix" i "existeix però no el pots veure" - això filtraria informació sobre recursos als quals la teva clau no pot accedir. Si estàs segur que el recurs existeix i hauries de tenir accés, revisa primer els teus scopes, després el teu context d'espai.

Estratègia de reintent

Per a codis que hauries de reintentar (429, 5xx), fes servir backoff exponencial:

async function callWithRetry(url: string, init: RequestInit) {
  const delays = [200, 800, 2000, 5000, 10000]; // ms
  for (const delay of [0, ...delays]) {
    if (delay) await sleep(delay);
    const res = await fetch(url, init);
    if (res.status >= 500 || res.status === 429) continue;
    return res;
  }
  throw new Error("retries exhausted");
}

No reintentis 4xx (excepte 429) - la petició està trencada; reintentar no la canviarà.

Rate limits (429)

Alguns endpoints estan limitats per IP - actualment els relacionats amb auth (/auth/magic-link, /auth/google, etc.). Quan excedeixes el límit, reps un 429.

Els endpoints de l'API a nivell d'espai (posts, comentaris, vots) no tenen rate limits publicats per clau avui. Si fas una migració massiva que xoca amb murs, escriu a [email protected] - podem pujar límits temporalment o recomanar un patró més amable.

Validació

Els cossos que fallen la validació de Pydantic retornen 422 amb un array detail dels camps infractors. La forma és l'estàndard de FastAPI - veure el format de resposta d'error de FastAPI o la referència OpenAPI per a exemples.