Bullgate Access · referência para produto e frontend

Erros e mensagens

Catálogo da fase 1 para transformar códigos estáveis do Bullgate em mensagens humanas, ações previsíveis e fluxos seguros. A copy é recomendada; código, status, campo e comportamento são o contrato.

Conferido no códigoContrato v0.1HTTP + AccessFlowAtualizado em 04/09/2026

Use a mensagem como base, não como protocoloO frontend decide texto, tom e idioma pelo code. Nunca compare a frase exibida, a mensagem de exceção ou o status isoladamente.

Três canais diferentes

Primeiro descubra que tipo de falha recebeu

Um erro HTTP encerra a chamada. Um feedback de flow mantém a jornada viva. Um erro de protocolo nasce no SDK antes de qualquer requisição.

`BullgateAccessError`

Resposta HTTP não bem-sucedida. Expõe status, code e, quando presente, field.

`flow.feedback`

Validação recuperável devolvida com HTTP 200. O novo snapshot substitui o anterior e governa as próximas ações.

`BullgateAccessProtocolError`

O SDK impediu uma ação ausente no snapshot local. É falha de integração ou estado de UI desatualizado, não mensagem de domínio.

Resposta HTTP{ "error": "invalid-email", "field": "email" }

Objeto no SDKerror.code === "invalid-email"; se a resposta não tiver JSON reconhecível, o fallback é http-{status}.

Feedback{ "code": "invalid-phone", "field": "phone", "retryAt": null } dentro do snapshot atualizado.

Cadastro, senha e providers sociais

Copies para entrada e provisionamento

As frases abaixo preservam a intenção do erro sem expor detalhes técnicos ou prometer um comportamento que não existe.

Status e código	Quando acontece	Copy sugerida	Ação da interface
`400 invalid-email`	E-mail ausente ou inválido no cadastro.	Digite um e-mail válido.	Focar `email` e preservar os demais campos.
`400 password-too-short`	Senha com menos de oito caracteres.	Use uma senha com pelo menos 8 caracteres.	Focar `password`; não apagar o e-mail.
`400 missing-fields`	Faltou `application` para criar o perfil local.	Revise os dados do cadastro e tente novamente.	Marcar o campo informado; se for `application`, tratar como integração incompleta.
`400 missing-token`	Google ou Apple foi chamado sem token utilizável.	Não foi possível iniciar com este provedor. Tente novamente.	Reabrir o SDK nativo do provider; não repetir o mesmo payload vazio.
`401 invalid-credentials`	Login por senha recusado. A resposta não revela se o e-mail existe.	E-mail ou senha incorretos.	Manter resposta neutra e oferecer recuperação quando disponível.
`401 invalid-token`	O token social expirou, é inválido ou não atende às garantias do provider.	A autorização não pôde ser validada. Tente novamente.	Solicitar um token novo pelo SDK oficial.
`409 email-taken`	Uma credencial Google/Apple nova trouxe e-mail que já pertence a outra identity. Não existe auto-link na fase 1.	Este e-mail já está associado a uma conta. Entre usando o método utilizado anteriormente.	Oferecer login ou recuperação; não vincular identities no cliente.
`409 authenticator-disabled`	A policy do environment não habilita senha, Google ou Apple naquela rota.	Esta forma de entrada não está disponível.	Ocultar o método após atualizar a configuração; não fazer fallback silencioso.
`409 application-not-provisioned`	A identity autenticou, mas o produto não resolveu um perfil local.	Sua conta foi reconhecida, mas o acesso ao produto ainda não está disponível.	Encaminhar para suporte ou correção do provisionamento; a sessão emitida é revogada.

Detalhe do cadastro por e-mail e senhaO BFF tenta login quando o cadastro direto encontra email-taken. Se a senha não corresponder, a resposta visível será invalid-credentials. O conflito social continua retornando email-taken.

Falhas que encerram a chamada

Erros HTTP do AccessFlow

Em conflitos de revisão ou ação, recarregue o flow antes de decidir a próxima tela. Nunca force localmente uma ação que o snapshot não oferece.

Status e código	Quando acontece	Copy sugerida	Ação da interface
`400 invalid-request`	Body ou ação obrigatória ausente.	Não foi possível continuar esta etapa.	Registrar como falha de integração; não repetir o mesmo body.
`409 protocol-version-unsupported`	Nenhuma versão enviada é aceita pelo servidor.	Atualize o aplicativo para continuar.	Bloquear a jornada e direcionar à atualização.
`400 intent-unsupported`	O intent solicitado não existe na versão atual.	Esta jornada não está disponível.	Corrigir a integração; não trocar o intent na interface.
`401 session-inactive`	Não há sessão Registration ativa para iniciar o flow.	Sua sessão expirou. Entre novamente.	Limpar somente o estado local da jornada e voltar à entrada.
`409 registration-not-pending`	A sessão não está mais aguardando continuação de cadastro.	Este cadastro não precisa mais desta etapa.	Restaurar a sessão e seguir o estado atual.
`400 native-client-invalid`	O `nativeClientId` não pertence ao environment autenticado.	Esta versão do aplicativo não está autorizada.	Tratar como configuração de release; não pedir outro ID ao usuário.
`409 request-id-conflict`	O mesmo `requestId` foi reutilizado com payload diferente.	Não foi possível repetir esta ação. Atualize e tente novamente.	Recarregar o estado; novo ID somente para uma nova intenção lógica.
`404 flow-not-found`	Flow inexistente, expirado, fora do escopo ou capability inválida.	Esta etapa expirou ou não está mais disponível.	Descartar o flow local e reiniciar a jornada.
`409 revision-conflict`	A UI enviou uma revisão anterior à persistida.	As informações mudaram. Atualizamos esta etapa para você.	Buscar o flow atual e renderizar o novo snapshot.
`409 action-not-available`	A ação não existe naquele estado ou revisão.	Esta ação não está mais disponível.	Recarregar o flow; nunca fabricar outra action.
`503 verification-delivery-unavailable`	O provider não conseguiu entregar ou aprovar o challenge.	Não conseguimos enviar o código agora. Tente novamente em instantes.	Preservar a etapa e permitir tentativa consciente; não afirmar que o número é inválido.

HTTP 200 · jornada continua

Feedback recuperável do flow

Sempre substitua o snapshot anterior pelo recebido. A presença ou ausência das próximas actions vale mais que a categoria aparente do feedback.

Código e campo	O que significa	Copy sugerida	Ação da interface
`invalid-phone` `phone`	O número não normaliza para E.164.	Digite um telefone válido, incluindo o código do país.	Focar telefone e manter `collectPhone`.
`phone-already-in-use` `phone`	Telefone sem verificação já pertence a outra identity; esse caminho não abre resolução.	Este telefone já está associado a outra conta.	Permitir corrigir ou pular somente se `skipRegistration` existir.
`phone-verification-no-active-code` `code`	Não há challenge ativo para confirmar ou reenviar.	Este código não está mais ativo. Solicite um novo.	Renderizar as actions do snapshot; não preservar o código digitado.
`missing-code` `code`	A confirmação chegou sem código.	Digite o código recebido.	Focar o campo sem consumir outra tentativa local.
`phone-verification-invalid-code` `code`	O código não corresponde ao challenge e ainda restam tentativas.	Código incorreto. Confira e tente novamente.	Limpar o campo e manter a confirmação se a action continuar presente.
`phone-verification-too-many-attempts` `code`	O limite do challenge foi atingido.	Este código foi bloqueado após várias tentativas.	Voltar ao estado devolvido e oferecer novo envio apenas se autorizado.
`phone-verification-resend-too-soon`	O cooldown ainda não terminou; `retryAt` pode acompanhar o feedback.	Aguarde um pouco antes de pedir outro código.	Desabilitar reenvio até `retryAt` e mostrar contagem local apenas como ajuda visual.
`phone-verification-rate-limited`	O limite de solicitações recentes da identity foi alcançado.	Muitas solicitações foram feitas. Aguarde antes de tentar novamente.	Não repetir automaticamente nem prometer um horário ausente.
`phone-conflict-email-mismatch` `previousEmail`	O e-mail informado não coincide com o identifier da identity anterior e ainda restam tentativas.	O e-mail informado não corresponde à conta anterior.	Limpar o campo e permitir nova tentativa se a action permanecer.
`phone-conflict-too-many-attempts` `previousEmail`	O limite de tentativas de prova do e-mail anterior foi atingido.	O limite de tentativas foi atingido. Recomece o processo.	Não oferecer transferência; obedecer às actions do novo snapshot.

Estado e disponibilidade

Sessão, fallback e falha operacional

`GET /session` retorna 401

O client React Native transforma esse status em null. A interface mostra estado deslogado; não precisa exibir mensagem de erro.

`503 access-unavailable`

Copy: “Não foi possível acessar sua conta agora. Tente novamente.” Preserve cookies e estado; indisponibilidade não prova logout.

`http-{status}`

Fallback do transport quando a resposta não contém JSON de erro reconhecível. Use mensagem genérica e registre status, rota e correlation ID disponíveis.

Logout só termina depois da revogaçãoSe o Access estiver indisponível, o adapter responde 503 access-unavailable e preserva o cookie. A copy deve permitir retry; não anuncie “Você saiu” antes do 204.

Princípios editoriais e de segurança

O que a mensagem deve — e não deve — dizer

Seja acionável

Diga o que a pessoa pode fazer agora.
Associe erro de campo ao controle correto.
Use retryAt quando ele existir.

Preserve neutralidade

Não revele se uma conta existe no login.
Não exponha provider, identity ID ou política interna sem necessidade.
Não transforme falha técnica em culpa da pessoa.

Não prometa

email-taken não significa que haverá auto-link.
503 não significa logout.
Feedback não autoriza ação ausente no snapshot.

Nunca mostre o código cru como copy finalrevision-conflict, application-not-provisioned e nomes semelhantes são contratos entre software. Eles podem entrar em log e telemetria, não na frase principal da tela.

React Native

Mapeie código para conteúdo e ação

Centralize a tradução. A tela consome uma decisão pronta e mantém o contrato separado do texto exibido.

Exemplo resumido

function presentAccessError(error: unknown) {
  if (!(error instanceof BullgateAccessError)) {
    return { message: "Não foi possível continuar.", action: "retry" };
  }

  switch (error.code) {
    case "invalid-credentials":
      return { message: "E-mail ou senha incorretos.", field: undefined };
    case "invalid-email":
      return { message: "Digite um e-mail válido.", field: error.field };
    case "revision-conflict":
      return { message: "As informações mudaram.", action: "reload-flow" };
    case "access-unavailable":
      return { message: "Não foi possível acessar sua conta agora.", action: "retry" };
    default:
      return { message: "Não foi possível continuar.", action: "retry" };
  }
}

Erros definidos pelo produtoIBullgateAccessApplication.ProvisionAsync também pode rejeitar com status, código e campo próprios. Esses códigos pertencem ao catálogo do produto consumidor e devem seguir as mesmas regras de copy, observabilidade e segurança.

Erros e mensagens

Primeiro descubra que tipo de falha recebeu

BullgateAccessError

flow.feedback

BullgateAccessProtocolError

Copies para entrada e provisionamento

Erros HTTP do AccessFlow

Feedback recuperável do flow

Sessão, fallback e falha operacional

GET /session retorna 401

503 access-unavailable

http-{status}

O que a mensagem deve — e não deve — dizer

Seja acionável

Preserve neutralidade

Não prometa

Mapeie código para conteúdo e ação

`BullgateAccessError`

`flow.feedback`

`BullgateAccessProtocolError`

`GET /session` retorna 401

`503 access-unavailable`

`http-{status}`