Gestion des erreurs

La Public API utilise un format d'erreur cohérent sur chaque endpoint et les codes de statut HTTP standard. Construisez votre client pour brancher sur le code de statut et lire le corps d'erreur partagé.

Schéma d'erreur

Chaque réponse d'erreur est un objet JSON avec les mêmes trois champs :

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

Champ	Type	Description
statusCode	number	Le code de statut HTTP, répété dans le corps.
error	string	Un libellé court, adapté aux machines, pour le statut (p. ex. Bad Request, Forbidden).
message	string	Une description lisible par un humain de ce qui s'est mal passé.

La réponse 429 (limite de débit) utilise la même forme plus un champ retryAfter supplémentaire — voir ci-dessous.

Codes de statut

400 — Bad Request

La requête était invalide ou ne peut pas être servie. Causes courantes :

• Un paramètre mal formé (par exemple, un ID qui n'est pas une chaîne hex de 24 caractères).
• Un champ requis manquant.
• Une valeur de paramètre de requête invalide.

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

Récupération : Corrigez la requête et réessayez. Celles-ci ne réussiront pas au retry sans changements.

401 — Unauthorized

L'authentification a échoué. L'en-tête Authorization est manquant, le token est mal formé, ou le token a expiré.

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

Récupération : Vérifiez l'en-tête Authorization: Bearer <token> et la validité du token. Si le token a expiré, créez-en un nouveau. Voir Authentification.

403 — Forbidden

Le token est valide mais n'a pas la permission pour cette ressource — typiquement un scope manquant, ou une intégration qui n'a pas été ajoutée au channel ou board qu'elle essaie d'atteindre.

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

Récupération : Accordez le scope requis au token, ou ajoutez l'intégration comme participante de la ressource. Ne réessayez pas à l'aveugle — la requête continuera d'échouer jusqu'à ce que l'accès soit accordé.

404 — Not Found

La ressource demandée n'existe pas ou n'est pas accessible avec ce token.

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

note

Certains endpoints renvoient 400 avec un message descriptif (par exemple, « Channel not found ») plutôt que 404 lorsqu'une ressource référencée est manquante. Gérez les deux lors de la validation des IDs.

Récupération : Vérifiez l'ID de la ressource et que le workspace de votre token la contient.

429 — Too Many Requests

Vous avez dépassé la limite de débit pour cet endpoint. La réponse porte un en-tête Retry-After (secondes jusqu'à la réinitialisation de la fenêtre) et un champ retryAfter dans le corps.

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

En-têtes de réponse sur 429 (et sur chaque réponse) :

• Retry-After — secondes à attendre avant de réessayer (sur 429 uniquement).
• X-RateLimit-Limit — le plafond par fenêtre de l'endpoint.
• X-RateLimit-Remaining — requêtes restantes dans la fenêtre en cours.
• X-RateLimit-Reset — moment de réinitialisation de la fenêtre.

Récupération : Attendez la période indiquée dans Retry-After, puis réessayez. Voir Limites de débit pour les conseils de backoff.

500 — Internal Server Error

Quelque chose s'est mal passé côté Copera.

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

Récupération : Réessayez avec un backoff exponentiel. Si cela persiste, la requête elle-même est correcte — l'échec est côté serveur.

Gérer les erreurs dans le code

Branchez sur le code de statut, et ne réessayez que les codes qui peuvent réussir au retry (429 et 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}`);
}

astuce

Ne réessayez pas 400, 401, 403 ou 404 — ils indiquent un problème avec la requête, le token ou les permissions qu'un retry ne corrigera pas. Remontez plutôt le message à l'appelant.