Status: Approved · v2 · SPEC-CONTRACTS-RESPONSE-001

depends_on: SPEC-API-OVERVIEW-001

used_by: IS-ZERO-00.2, IS-MVP-15.1

Contratos de resposta e erro

Envelope único e semântica estável para API, mocks e clients.

Tipos oficiais

export type ApiWarning = Readonly<{
  code: string;
  message: string;
  target?: Readonly<{ type: string; id: ID }>;
}>;

export type PaginationMeta = Readonly<{
  page: number;
  pageSize: number;
  totalItems: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
}>;

export type ApiMeta = Readonly<{
  requestId: string;
  timestamp: ISODateString;
  pagination?: PaginationMeta;
  warnings?: readonly ApiWarning[];
}>;

export type ApiFieldError = Readonly<{
  field: string;
  code: string;
  message: string;
}>;

export type ApiError = Readonly<{
  code: ApiErrorCode;
  message: string;
  details?: Readonly<Record<string, unknown>>;
  fieldErrors?: readonly ApiFieldError[];
  retryAfterSeconds?: number;
}>;

export type ApiSuccessResponse<T extends object> = Readonly<{
  ok: true;
  data: T;
  meta: ApiMeta;
}>;

export type ApiErrorResponse = Readonly<{
  ok: false;
  error: ApiError;
  meta: ApiMeta;
}>;

export type ApiResponse<T extends object> =
  | ApiSuccessResponse<T>
  | ApiErrorResponse;

Semântica HTTP

• 200: leitura/mutação concluída.
• 201: recurso criado.
• 202: processamento aceito quando realmente assíncrono.
• Evitar 204; retornar OperationResponse mantém envelope consistente.
• 400: request malformado tecnicamente.
• 401/403/404/409/410/413/422/429/500: conforme catálogo.

Listas

data é sempre objeto: { items: [...] }. A paginação fica em meta.pagination. Lista vazia é sucesso e não erro.

Warnings

Warnings informam estados como abandoned, incomplete, provisional ou canonical redirect assistido sem transformar a resposta em falha.

Catálogo mínimo de erros

• VALIDATION_ERROR
• UNAUTHORIZED
• PERMISSION_REQUIRED
• NOT_FOUND
• CONFLICT
• GONE
• RATE_LIMITED
• INTERNAL_ERROR
• NETWORK_ERROR (client-only)
• IDEMPOTENCY_CONFLICT
• PAYMENT_EXPIRED
• INSUFFICIENT_CREDITS
• ENTITY_SUSPENDED
• PRIVACY_RESTRICTED

Regras para clientes

• ApiClient converte falha de rede em estado técnico NETWORK_ERROR; não inventa HTTP.
• Hooks mapeiam códigos para mensagens/ações centralizadas.
• Field errors permanecem estruturados.
• Request ID deve ser exibível em detalhes de suporte.

Critérios de aceite

• Toda rota e handler usa envelope.
• Nenhum response é array solto.
• Erros internos não vazam stack.
• Lista vazia é sucesso.
• Mock e API compartilham os mesmos tipos.