Erros

A Hub API retorna erros em um formato JSON único, alinhado ao schema OpenAPI Error registrado em apps/api/src/lib/openapi/schemas.ts. Esta página descreve o contrato exato, os códigos HTTP usados em produção e como construir um handler resiliente do lado do cliente.

Formato canônico (JSON)

Todo erro retornado pelos route handlers segue este shape mínimo:

{
  "error": "string descrevendo o erro",
  "details": {}
}

O campo details é opcional e usado principalmente em respostas de validação. Para erros de schema (Zod), o middleware validateBody em apps/api/src/lib/middleware/validate.ts preenche details com o mapa fieldErrors retornado por result.error.flatten().

Exemplo de erro de validação:

{
  "error": "Validation error",
  "details": {
    "email": ["Invalid email"],
    "password": ["Password must be at least 8 characters"]
  }
}

Exemplo de erro de permissão emitido por requirePermission:

{
  "error": "Insufficient permissions",
  "required": "channels:edit"
}

Códigos HTTP utilizados

A Hub API utiliza um subconjunto enxuto de códigos HTTP. Cada um tem semântica fixa e o cliente deve tratá-los de forma distinta:

Respostas a permissão

Quando uma rota exige uma permissão específica e o caller não a possui, a resposta inclui o par resource:action esperado:

{
  "error": "Insufficient permissions",
  "required": "inbox:edit"
}

Esse formato vem de requirePermission em apps/api/src/lib/middleware/auth.ts e permite ao cliente sugerir ao admin quais escopos conceder à membership.

Respostas a auth

Códigos de erro internos

A Hub API não utiliza um campo code enumerado em todas as respostas. A identificação do erro é feita pela combinação de status HTTP + error (string canônica). Algumas strings recorrentes aparecem em múltiplos endpoints e podem ser tratadas como códigos lógicos:

Missing authorization header
Missing authorization
Invalid or expired token
Invalid or revoked API key
API key has expired
No refresh token
Insufficient permissions
Unauthorized
Internal auth not configured
Cron auth not configured

Validation error
Invalid JSON body
orgId is required
phoneNumber required
Token is required
Confirmation required

Not found
Lead not found
Channel not found
Session not found
Link not found
Link expired
Link already used
Slug already taken
Key already exists in org
Name already exists
Pipeline already exists for this provider + externalId
Channel is not connected
Not a member
Not a member of organization
Not a QR_CODE channel
Not a WWABA channel

Langfuse not configured
Failed to save to Langfuse
Failed to fetch from Langfuse
Langfuse upstream error
Provider fetch failed
Provider discovery failed
No credential set found
No credential set found for provider

Boas práticas para handler de erro

Um cliente bem comportado deve seguir estes princípios ao consumir a Hub API.

const res = await fetch(`${HUB_API}/orgs/${orgId}/channels`, {
  headers: { Authorization: `Bearer ${token}` },
});

if (!res.ok) {
  const body = await res.text();
  let parsed: { error?: string; details?: unknown } = {};
  try {
    parsed = JSON.parse(body);
  } catch {
    // resposta não-JSON (HTML do ingress, plain text de proxy)
  }
  throw new HubApiError(res.status, parsed.error ?? body, parsed.details);
}

const data = await res.json();

switch (status) {
  case 400: return showFieldErrors(details);
  case 401: return redirectToLogin();
  case 403: return showForbiddenBanner(parsed.required);
  case 404: return showNotFound();
  case 409: return showConflictDialog(parsed.error);
  case 410: return refreshEphemeralToken();
  case 413: return showFileTooLarge();
  case 429: return scheduleRetry(parseRetryAfter(headers));
  case 502: return showUpstreamDegraded();
  default: return showGenericError();
}

function parseRetryAfter(headers: Headers): number {
  const raw = headers.get("Retry-After");
  const seconds = raw ? parseInt(raw, 10) : 60;
  const jitter = Math.random() * 1000;
  return seconds * 1000 + jitter;
}