Envelope e erros

O envelopeCopy Anchor Link

Toda resposta JSON vem no mesmo envelope:

{ "success": true, "data": { "uid": "…" } }
{ "success": false, "error": { "code": "SEAT_NOT_ACTIVE", "message": "…", "details": { } } }

• Os handlers só montam o lado do sucesso, com reply.ok (200), reply.created (201), reply.accepted (202) e reply.noContent (204). Pra falhar, o handler lança um AppError, e só o errorHandler transforma isso em HTTP.
• code é o contrato. É estável e o cliente decide por ele. message é texto pra gente, em inglês, e pode mudar.
• details é opcional e traz dados de máquina (por exemplo retryAt, maxDays, retryAfterSeconds).
• Uma página paginada põe nextCursor ao lado de data, ou dentro de data. Veja Paginação.

Exceções ao envelopeCopy Anchor Link

A família AppErrorCopy Anchor Link

backend/src/core/contracts/errors.ts define a base e as classes genéricas. Cada domínio lança essas classes ou um DomainError com código próprio.

Códigos que não saem de uma classe:

Códigos de domínio (422)Copy Anchor Link

Contas, vagas e onboarding

Consentimento

Canais e pareamento

Importação de histórico (fila): NOTHING_TO_SYNC, NO_OPEN_OFFER, OFFER_EXPIRED, ALREADY_ADMITTED, NOT_IN_QUEUE, SEAT_KEY_GONE (a vaga não tem chave: nunca foi ativada, ou o consentimento foi retirado).

Backoffice: SELF_INVITE, MEMBER_UNKNOWN, SELF_CHANGE, LAST_OWNER (membros operadores); TOO_MANY, PRODUCT_NOT_ALLOWED, BUDGET_EXCEEDED, ORDER_UNKNOWN, QUOTE_NOT_AN_EXTENSION, QUOTE_EXPIRED, PROXY_UNREACHABLE, PROVIDER_UNKNOWN, PROVIDER_NOT_CONFIGURED (proxies e fornecedores).

Login: os códigos OTP_* (401)Copy Anchor Link

Todos respondem 401 em POST /auth/otp/verify (classe OtpRefusedError, backend/src/domains/auth/errors.ts):

RATE_LIMITED (429) vale no login (request, verify, resend), no link de consentimento e no pareamento pelo celular da pessoa. Veja Limites de taxa.

Lendo um erroCopy Anchor Link

const res = await fetch(`${API}/seats/${seatUid}/activate`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${token}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ guardianAttestation: true }),
});
const body = await res.json();
if (!body.success) {
  switch (body.error.code) {
    case "CONSENT_REQUIRED":
      return goTo("await_consent");
    case "RATE_LIMITED":
      return wait(body.error.details.retryAfterSeconds);
    default:
      return showGeneric(body.error.message);
  }
}

FontesCopy Anchor Link

• backend/src/http/response.ts, backend/src/http/app.ts, backend/src/http/middleware/error-handler.ts
• backend/src/core/contracts/errors.ts
• DomainError/AppError em backend/src/domains/** (levantamento por grep nas classes e nas strings de código)
• backend/src/domains/consents/verification/errors.ts, backend/src/domains/subscriptions/use-cases/monitoring.ts
• backend/src/http/routes/system/health.route.ts
• backend/src/domains/auth/errors.ts
• .specs/features/redesign/api-gaps.md (G-19, G-42)