Gestione errori

La Public API usa un formato di errore coerente su ogni endpoint e codici di stato HTTP standard. Costruisci il client per fare branching sul codice di stato e leggere il body di errore condiviso.

Schema di errore

Ogni response di errore è un oggetto JSON con gli stessi tre campi:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You are not allowed to access boards"
}

Field	Type	Description
statusCode	number	The HTTP status code, repeated in the body.
error	string	A short, machine-friendly label for the status (e.g. Bad Request, Forbidden).
message	string	A human-readable description of what went wrong.

La response 429 (rate limit) usa la stessa forma più un campo extra retryAfter — vedi sotto.

Codici di stato

400 — Bad Request

La richiesta non era valida o non può essere servita. Cause comuni:

• Un parametro malformato (ad esempio, un ID che non è una stringa hex di 24 caratteri).
• Un campo obbligatorio manca.
• Un valore di query parameter non valido.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid parameter: boardId"
}

Recovery: Correggi la richiesta e ritenta. Queste non avranno successo al retry senza modifiche.

401 — Unauthorized

L'autenticazione è fallita. L'header Authorization manca, il token è malformato o il token è scaduto.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid token"
}

Recovery: Controlla l'header Authorization: Bearer <token> e la validità del token. Se il token è scaduto, creane uno nuovo. Vedi Autenticazione.

403 — Forbidden

Il token è valido ma manca il permesso per questa risorsa — tipicamente uno scope mancante, oppure un'integrazione che non è stata aggiunta al channel o alla board che sta cercando di raggiungere.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You are not allowed to access boards"
}

Recovery: Concedi lo scope richiesto al token, oppure aggiungi l'integrazione come participant della risorsa. Non ritentare alla cieca — la richiesta continuerà a fallire finché l'accesso non è concesso.

404 — Not Found

La risorsa richiesta non esiste o non è accessibile con questo token.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Not Found - The requested resource was not found"
}

nota

Alcuni endpoint restituiscono 400 con un messaggio descrittivo (ad esempio, "Channel not found") anziché 404 quando manca una risorsa referenziata. Gestisci entrambi quando validi gli ID.

Recovery: Verifica l'ID della risorsa e che il workspace del token la contenga.

429 — Too Many Requests

Hai superato il rate limit per quell'endpoint. La response porta un header Retry-After (secondi fino al reset della finestra) e un campo retryAfter nel body.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests, please try again later",
  "retryAfter": 27
}

Header di response su 429 (e su ogni response):

• Retry-After — secondi da attendere prima di ritentare (solo su 429).
• X-RateLimit-Limit — il cap per-window dell'endpoint.
• X-RateLimit-Remaining — richieste rimaste nella finestra corrente.
• X-RateLimit-Reset — quando la finestra si resetta.

Recovery: Attendi il periodo in Retry-After, poi ritenta. Vedi Rate limit per la guida al backoff.

500 — Internal Server Error

Qualcosa è andato storto lato Copera.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Internal Server Error - Something went wrong on the server"
}

Recovery: Ritenta con exponential backoff. Se persiste, la richiesta in sé va bene — il fallimento è server-side.

Gestire gli errori nel codice

Fai branching sul codice di stato e ritenta solo i codici che possono avere successo al retry (429 e 5xx):

async function callApi(url, init, attempt = 0) {
  const res = await fetch(url, init);

  if (res.ok) return res.json();

  // Retry rate limits and server errors with backoff.
  if ((res.status === 429 || res.status >= 500) && attempt < 5) {
    const retryAfter = Number(res.headers.get("Retry-After"));
    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 2 ** attempt * 1000; // exponential backoff fallback
    await new Promise((r) => setTimeout(r, waitMs));
    return callApi(url, init, attempt + 1);
  }

  const error = await res.json();
  throw new Error(`${error.statusCode} ${error.error}: ${error.message}`);
}

suggerimento

Non ritentare 400, 401, 403 o 404 — indicano un problema con la richiesta, il token o i permessi che un retry non risolverà. Propaga il message al chiamante.