Erros

Todo erro da API responde o mesmo envelope:

{
  "error": {
    "code": "last_owner",
    "message": "the organization must keep at least one owner"
  }
}

string

Estável. É o contrato — ramifique nele.

string

Para uma pessoa. Pode mudar de redação entre versões, e pode vir num idioma que você não pediu. Nunca faça parse dela.

Mapeie os códigos para os seus próprios textos, e caia de volta para message quando o código for desconhecido — assim um código novo degrada para algo legível em vez de degradar para nada.

Códigos por status

400 — a requisição está errada

Código	Significado
`invalid_request`	Corpo malformado, campo faltando, ou parâmetro inválido
`weak_password`	Menos de 8 caracteres, ou sem minúscula, maiúscula ou dígito
`breached_password`	A senha aparece num corpus público de vazamentos. Conferida por k-anonimato — ela nunca sai do nosso processo
`invalid_token`	Token de uso único inválido, expirado ou já usado
`unknown_permission`	Uma permissão fora do catálogo
`confirmation_mismatch`	O nome da organização digitado não bate
`unsupported_type`	Content type do upload não é JPEG, PNG, WebP ou GIF
`invalid_size`	`size_bytes` do upload é 0, negativo ou passa de 5 MiB

401 — sem credencial válida

Código	Significado
`unauthorized`	Credencial ausente, malformada, expirada ou revogada; também “não é membro daquela organização”
`invalid_credentials`	E-mail ou senha errados — e a reconferência de senha numa ação de step-up, que responde aqui e não `403`: quem chama está autenticado, o que não conferiu foi a credencial que a pessoa acabou de digitar
`invalid_challenge`	Desafio de dois fatores inválido, expirado, já gasto, sem tentativas, ou de outro ambiente
`invalid_code`	Código TOTP, de recuperação ou por e-mail errado
`invalid_identity_hash`	O HMAC não verifica para este `external_id`
`invalid_grant`	Um login social cujo state é desconhecido, expirou ou já foi gasto — ou cujo código o provedor recusou

403 — autenticado, não autorizado

Código	Significado
`forbidden`	Seu papel não carrega a permissão — ou você está tentando mudar ou remover a si mesmo
`role_exceeds_your_own`	O papel que você está concedendo carrega permissões que o seu próprio não tem
`owner_locked`	O papel owner precisa manter `roles:manage`
`system_role`	Papéis de sistema não podem ser renomeados
`origin_not_allowed`	Esta chave publicável não aceita chamadas desta origem
`unverified_session`	Esta sessão de contato afirma uma identidade que nunca foi comprovada. Sessões anônimas não são afetadas — veja modo federado
`waitlisted`	Este contato ainda está na fila e não pode ter sessão — veja lista de espera

404 — não é aqui

Código	Significado
`not_found`	Não existe, ou existe em outra organização ou outro ambiente
`unknown_provider`	Este provedor social não é suportado

404 também é como leituras cross-tenant e cross-ambiente respondem. Ele nunca revela que o recurso existe em outro lugar — o id que você tem simplesmente não é endereçável com a credencial que você tem.

409 — o estado diz não

Código	Significado
`email_taken`	Já existe um usuário com este e-mail
`already_member`	Este usuário já é membro
`invite_exists`	Já existe um convite pendente para este e-mail
`last_owner`	A organização precisa manter pelo menos um owner
`role_exists`	Já existe um papel com este nome
`role_in_use`	Mova os membros dele para outro papel primeiro
`already_enabled`	Os dois fatores já estão ligados — desligue antes
`waitlist_closed`	Este ambiente não está com lista de espera
`setup_required`	Inicie a configuração dos dois fatores primeiro
`two_factor_disabled`	Ative os dois fatores antes de regerar códigos de recuperação
`environment_not_hosted`	Este ambiente é federado; identifique via `/v1/boot`
`environment_not_federated`	Este ambiente é hosted; mude para federado
`oauth_provider_not_configured`	Este ambiente não tem aplicação OAuth para o provedor

422 — falhou permanentemente

Código	Significado
`job_failed_permanently`	Callback interno de job: dê ack na mensagem, um retry não tem como dar certo

429 — demais

Código	Significado
`rate_limited`	Requisições demais. `Retry-After` carrega a janela em segundos

Veja Rate limits.

5xx — nossos

Código	Status	Significado
`internal_error`	500	Algo falhou do nosso lado. Pode tentar de novo.
`job_failed`	500	Callback interno de job: tente a mensagem de novo
`provider_unavailable`	502	Não foi possível alcançar um provedor social

501 — o servidor não sabe fazer isso

Código	Significado
`two_factor_unavailable`	A verificação em duas etapas está indisponível no servidor
`uploads_unavailable`	O armazenamento de arquivos está indisponível no servidor
`federated_identity_unavailable`	A identidade federada está indisponível no servidor
`jwt_unavailable`	A emissão de JWT de sessão está indisponível no servidor
`social_login_unavailable`	O login social está indisponível no servidor

São estados da plataforma, não erros do usuário. GET /v1/session informa two_factor_available e uploads_available para um cliente esconder o recurso em vez de descobrir aqui.

Tratando

const MESSAGES: Record<string, string> = {
  last_owner: "A organização precisa de pelo menos um owner.",
  role_in_use: "Mova os membros deste papel para outro antes.",
  origin_not_allowed: "Este domínio não está na lista permitida da chave.",
};

async function call(path: string, init?: RequestInit) {
  const response = await fetch(path, init);
  if (response.ok) return response.status === 204 ? null : response.json();

  const { error } = await response.json();
  // Um código desconhecido degrada para a mensagem da própria API, não para nada.
  throw new Error(MESSAGES[error.code] ?? error.message);
}

Duas coisas que não são erros

Um valor de paginação fora da faixa volta para o padrão em vez de responder 400. Não conte com um 400 para pegar um tamanho de página inválido. 202 nos endpoints não enumeráveis é sucesso. Não significa “na fila” e não significa que o endereço existe — significa que a resposta seria a mesma de qualquer jeito.

Visão geral

Endpoints

Códigos por status

400 — a requisição está errada

401 — sem credencial válida

403 — autenticado, não autorizado

404 — não é aqui

409 — o estado diz não

422 — falhou permanentemente

429 — demais

5xx — nossos

501 — o servidor não sabe fazer isso

Tratando

Duas coisas que não são erros

​Códigos por status

​400 — a requisição está errada

​401 — sem credencial válida

​403 — autenticado, não autorizado

​404 — não é aqui

​409 — o estado diz não

​422 — falhou permanentemente

​429 — demais

​5xx — nossos

​501 — o servidor não sabe fazer isso

​Tratando

​Duas coisas que não são erros

Códigos por status

400 — a requisição está errada

401 — sem credencial válida

403 — autenticado, não autorizado

404 — não é aqui

409 — o estado diz não

422 — falhou permanentemente

429 — demais

5xx — nossos

501 — o servidor não sabe fazer isso

Tratando

Duas coisas que não são erros