> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Erros
> Um envelope, códigos estáveis, e uma mensagem escrita para uma pessoa.
Todo erro da API responde o mesmo envelope:
```json theme={null}
{
"error": {
"code": "last_owner",
"message": "the organization must keep at least one owner"
}
}
```
Estável. É o contrato — ramifique nele.
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](/pt-br/customer-auth/federated) |
| `waitlisted` | Este contato ainda está na fila e não pode ter sessão — veja [lista de espera](/pt-br/customer-auth/waitlist) |
### 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](/pt-br/api-reference/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
```ts theme={null}
const MESSAGES: Record = {
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.