Tratamento de Erros

A Public API usa um formato de erro consistente em todos os endpoints e codigos de status HTTP padrao. Construa seu cliente para ramificar pelo codigo de status e ler o corpo de erro compartilhado.

Schema de erro

Toda resposta de erro e um objeto JSON com os mesmos tres campos:

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

Campo	Tipo	Descricao
statusCode	number	O codigo de status HTTP, repetido no corpo.
error	string	Um rotulo curto e amigavel para maquinas que descreve o status (por exemplo, Bad Request, Forbidden).
message	string	Uma descricao legivel do que deu errado.

A resposta 429 (rate limit) usa o mesmo formato, mais um campo extra retryAfter — veja abaixo.

Codigos de status

400 — Bad Request

A requisicao era invalida ou nao pode ser atendida. Causas comuns:

• Um parametro malformado (por exemplo, um ID que nao e uma string hexadecimal de 24 caracteres).
• Um campo obrigatorio ausente.
• Um valor invalido em um parametro de query.

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

Recuperacao: Corrija a requisicao e tente novamente. Sem alteracoes, o retry nao tera sucesso.

401 — Unauthorized

A autenticacao falhou. O header Authorization esta ausente, o token esta malformado ou o token expirou.

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

Recuperacao: Verifique o header Authorization: Bearer <token> e a validade do token. Se o token expirou, crie um novo. Veja Autenticacao.

403 — Forbidden

O token e valido, mas nao tem permissao para este recurso — normalmente um escopo ausente, ou uma integracao que nao foi adicionada ao channel ou board que esta tentando acessar.

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

Recuperacao: Conceda o escopo necessario ao token, ou adicione a integracao como participante do recurso. Nao tente novamente as cegas — a requisicao continuara falhando ate que o acesso seja concedido.

404 — Not Found

O recurso solicitado nao existe ou nao pode ser acessado com este token.

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

observação

Alguns endpoints retornam 400 com uma mensagem descritiva (por exemplo, "Channel not found") em vez de 404 quando um recurso referenciado esta ausente. Trate ambos ao validar IDs.

Recuperacao: Verifique o ID do recurso e se o workspace do seu token o contem.

429 — Too Many Requests

Voce excedeu o limite de requisicoes desse endpoint. A resposta traz um header Retry-After (segundos ate a janela reiniciar) e um campo retryAfter no corpo.

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

Headers de resposta no 429 (e em toda resposta):

• Retry-After — segundos para aguardar antes de tentar novamente (apenas no 429).
• X-RateLimit-Limit — o limite do endpoint por janela.
• X-RateLimit-Remaining — requisicoes restantes na janela atual.
• X-RateLimit-Reset — quando a janela reinicia.

Recuperacao: Aguarde o periodo indicado em Retry-After e tente novamente. Veja Limites de Requisicao para orientacoes de backoff.

500 — Internal Server Error

Algo deu errado do lado da Copera.

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

Recuperacao: Tente novamente com backoff exponencial. Se persistir, a requisicao em si esta correta — a falha e do lado do servidor.

Tratando erros no codigo

Ramifique pelo codigo de status e faca retry apenas dos codigos que podem ter sucesso ao tentar de novo (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}`);
}

dica

Nao faca retry de 400, 401, 403 ou 404 — eles indicam um problema com a requisicao, o token ou as permissoes que um retry nao vai resolver. Em vez disso, exiba a message para quem chamou.