Fehlerbehandlung

Die Public API verwendet ein einheitliches Fehlerformat über alle Endpunkte und Standard-HTTP-Statuscodes. Bauen Sie Ihren Client so, dass er auf dem Statuscode verzweigt und den gemeinsamen Fehler-Body liest.

Fehler-Schema

Jede Fehlerantwort ist ein JSON-Objekt mit denselben drei Feldern:

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

Feld	Typ	Beschreibung
statusCode	number	Der HTTP-Statuscode, im Body wiederholt.
error	string	Kurzes, maschinenfreundliches Label für den Status (z. B. Bad Request, Forbidden).
message	string	Menschenlesbare Beschreibung, was schiefgelaufen ist.

Die 429-Antwort (Rate-Limit) hat dieselbe Form plus ein zusätzliches Feld retryAfter — siehe unten.

Statuscodes

400 — Bad Request

Die Anfrage war ungültig oder kann nicht bedient werden. Häufige Ursachen:

• Ein fehlerhafter Parameter (z. B. eine ID, die kein 24-stelliger Hex-String ist).
• Ein Pflichtfeld fehlt.
• Ein ungültiger Query-Parameterwert.

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

Wiederherstellung: Anfrage korrigieren und erneut senden. Ohne Änderung gelingen diese Retries nicht.

401 — Unauthorized

Authentifizierung fehlgeschlagen. Der Header Authorization fehlt, das Token ist fehlerhaft oder abgelaufen.

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

Wiederherstellung: Header Authorization: Bearer <token> und Token-Gültigkeit prüfen. Bei abgelaufenem Token ein neues erstellen. Siehe Authentifizierung.

403 — Forbidden

Das Token ist gültig, hat aber keine Berechtigung für diese Ressource — typischerweise ein fehlender Scope oder eine Integration, die dem Channel oder Board noch nicht hinzugefügt wurde.

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

Wiederherstellung: Dem Token den erforderlichen Scope gewähren oder die Integration als Teilnehmer der Ressource hinzufügen. Nicht blind retryen — die Anfrage scheitert, bis Zugriff gewährt ist.

404 — Not Found

Die angeforderte Ressource existiert nicht oder ist mit diesem Token nicht erreichbar.

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

hinweis

Manche Endpunkte liefern bei fehlender referenzierter Ressource 400 mit einer beschreibenden Meldung (z. B. „Channel not found“) statt 404. Behandeln Sie beide beim Validieren von IDs.

Wiederherstellung: Ressourcen-ID prüfen und sicherstellen, dass der Workspace Ihres Tokens sie enthält.

429 — Too Many Requests

Sie haben das Rate-Limit für diesen Endpunkt überschritten. Die Antwort enthält den Header Retry-After (Sekunden bis zum Fenster-Reset) und das Feld retryAfter im Body.

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

Response-Header bei 429 (und bei jeder Antwort):

• Retry-After — Sekunden bis zum erneuten Versuch (nur bei 429).
• X-RateLimit-Limit — Obergrenze des Endpunkts pro Fenster.
• X-RateLimit-Remaining — verbleibende Anfragen im aktuellen Fenster.
• X-RateLimit-Reset — wann das Fenster zurückgesetzt wird.

Wiederherstellung: Die in Retry-After angegebene Zeit warten, dann erneut versuchen. Siehe Rate Limits für Backoff-Hinweise.

500 — Internal Server Error

Etwas ist auf Seiten von Copera schiefgelaufen.

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

Wiederherstellung: Mit exponentiellem Backoff retryen. Wenn es anhält, ist die Anfrage selbst in Ordnung — der Fehler liegt serverseitig.

Fehler im Code behandeln

Verzweigen Sie auf dem Statuscode und retryen Sie nur Codes, die bei erneutem Versuch gelingen können (429 und 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}`);
}

tipp

Retryen Sie nicht bei 400, 401, 403 oder 404 — sie zeigen ein Problem mit Anfrage, Token oder Berechtigungen, das ein Retry nicht behebt. Geben Sie stattdessen message an den Aufrufer weiter.