Códigos de erro
Como o Authio informa erros nos endpoints de protocolo e na API administrativa, o status HTTP de cada tipo de falha e os códigos que você mais deve encontrar.
O Authio responde erros em dois formatos. Os endpoints de protocolo falam OAuth 2.0, para que bibliotecas padrão os entendam; a API administrativa embrulha todo erro no envelope dela, com um errorCode estável no topo. Os dois levam os mesmos códigos por baixo, então uma falha relatada por uma integração pode ser cruzada com os logs do Authio.
Erros nos endpoints de protocolo
Os endpoints sob /protocol/openid-connect/ respondem com os campos do RFC 6749 §5.2 — error e error_description —, mais error_code, o código por trás do erro:
400 Bad RequestJSON
{
"error": "invalid_grant",
"error_description": "Authorization code expired!",
"error_code": "AuthorizationCodeExpired"
}error | HTTP | Códigos por trás dele |
|---|---|---|
invalid_client | 401 | InvalidClientCredentials: um segredo errado, ou um segredo enviado por um método para o qual o client não está registrado. |
invalid_grant | 400 | AuthorizationCodeNotFound, AuthorizationCodeExpired, AuthorizationCodeClientMismatch, MissingCodeChallenge, MissingCodeVerifier, InvalidCodeVerifier, TokenExpired, RefreshTokenFailed, InvalidUserAuthentication, UserLockedOut, EmailNotConfirmed, UserSuspended |
invalid_request | 400 | InvalidRequest, InvalidRedirectUri, MissingGrantType, MissingCodeChallengeMethod, PkceMethodNotAllowed, RequiredFields, e um client que não existe ou está inativo. |
invalid_scope | 400 | InvalidScope: um escopo que o client não habilitou. |
invalid_target | 400 | InvalidTarget: um resource que o client não pode alcançar. |
unauthorized_client | 400 | GrantTypeDisabled; AccountNotEntitled quando a assinatura por trás da aplicação não está ativa. |
unsupported_grant_type | 400 | UnsupportedGrantType |
unsupported_response_type | 400 | UnsupportedResponseType |
access_denied | 400 | Um pedido de dispositivo negado; McpIntegrationNotIncluded, ConnectedAccountsNotIncluded ou IntegrationLicenseSuspended quando o plano não cobre o pedido. |
authorization_pending, slow_down, expired_token | 400 | Consulta do fluxo de dispositivo: continue esperando, consulte mais devagar ou comece de novo. |
temporarily_unavailable | 429 ou 5xx | Limite de taxa atingido, ou um serviço de que o Authio depende está indisponível. Tente de novo mais tarde. |
server_error | 500 | Algo falhou do lado do Authio. |
A introspecção e a revogação nunca falham por causa do próprio token: um token inválido, expirado ou desconhecido recebe 200 com active: false da introspecção, e um 200 simples da revogação. O UserInfo responde 401 com invalid_token, ou 403 com insufficient_scope, cada um com o cabeçalho WWW-Authenticate.
Durante um login no navegador, os erros não são JSON. Enquanto o redirect_uri não está comprovado, eles aparecem na tela de erro do client; depois disso, voltam ao redirect_uri com error, error_description, state e iss.
Erros na API administrativa
A API administrativa responde toda falha com o envelope dela: success é false, o status HTTP diz que tipo de falha foi, errorCode dá o nome dela e notifications a explica para uma pessoa. Um erro de validação aponta cada campo recusado:
400 Bad RequestJSON
{
"statusCode": 400,
"success": false,
"notifications": [
{
"message": "The description is too long.",
"field": "description",
"code": "ValidationFailed"
}
],
"errorCode": "ValidationFailed",
"requestId": "0HN8R3K5QJ2VA:00000004"
}Os códigos são nomes, como NotFound ou AlreadyExists, e o mesmo nome pode vir de áreas diferentes: um realm inexistente e um client inexistente respondem os dois NotFound. Leia o código junto com o endpoint que você chamou e guarde o requestId ao relatar um problema. O envelope em si está descrito em API administrativa.
Status HTTP por tipo de falha
Todo erro que o Authio levanta declara que tipo de falha é, e cada tipo responde com um status:
| Tipo | HTTP | Significado |
|---|---|---|
Invalid | 400 | A requisição trouxe algo que as regras recusam. |
Unauthorized | 401 | Quem chama não provou quem é, ou a prova não se sustentou. |
PaymentRequired | 402 | A ação exige um plano ou um pagamento que a conta não tem. |
Forbidden | 403 | Quem chama é conhecido, mas não pode fazer isso. |
NotFound | 404 | O que a requisição cita não existe, ou não é visível para quem chama. |
Conflict | 409 | A requisição choca com o estado atual do que ela cita. |
Gone | 410 | O que a requisição cita existiu e não está mais disponível. |
Locked | 423 | O que a requisição cita está bloqueado para a ação. |
NotImplemented | 501 | A ação não é suportada aqui. |
UpstreamFailure | 502 | Um serviço de que o Authio depende respondeu com falha. |
Unavailable | 503 | O recurso está temporariamente indisponível. |
UpstreamTimeout | 504 | Um serviço de que o Authio depende não respondeu a tempo. |
| Qualquer coisa inesperada | 500 | Uma falha que quem chama não poderia ter causado. |
Requisições recusadas antes de chegar a um endpoint usam o mesmo envelope: 404 para uma rota desconhecida (NotFound), 405 para um método que a rota não aceita (MethodNotAllowed), 415 para um corpo que não é JSON (UnsupportedMediaType) e 429 para um limite de taxa (TooManyRequests).
Códigos comuns
Requisições e validação
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
ValidationFailed | 400 | O corpo quebrou uma regra, ou não pôde ser lido. | Corrija os campos apontados em notifications. |
RequiredFields | 400 | Faltam campos obrigatórios. | Envie todos os campos que o endpoint exige. |
NotFound | 404 | A rota ou o recurso não existe, ou pertence a outra conta. | Confira o caminho e os IDs. |
Conflict | 409 | A alteração choca com dados salvos nesse meio-tempo. | Leia o recurso de novo e tente outra vez. |
TooManyRequests | 429 | O limite de taxa foi atingido. | Espere os segundos indicados em Retry-After. |
TemporarilyUnavailable | 503 | O Authio não conseguiu falar com o banco de dados ou o cache por um instante; nada foi alterado. | Espere os segundos indicados em Retry-After e envie a mesma requisição de novo. |
UpstreamFailure, RequestTimeout | 502, 503, 504 | Um serviço de que o Authio depende falhou ou não respondeu. | Tente de novo mais tarde. |
UnexpectedError | 500 | Algo falhou do lado do Authio. | Tente de novo; se persistir, fale com o suporte informando o requestId. |
Usuários e login
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
Unauthorized | 401 | A chamada não leva credenciais válidas. | Envie um segredo de API ou um bearer token do realm da plataforma. |
Forbidden | 403 | Quem chama está autenticado, mas não tem a permissão. | Conceda o papel, ou permita-o no segredo de API. |
InvalidCredentials | 401 | O usuário ou a senha estão errados. | Confira e tente de novo. |
LockedOut | 401 | Tentativas demais com falha: a conta fica bloqueada por um tempo. | Espere o bloqueio terminar. |
PasswordExpired | 401 | A senha precisa ser renovada. | Renove pelo link enviado por e-mail. |
AccountNotConfirmed | 401 | O endereço com que a conta foi criada não foi confirmado. | Confirme-o e entre de novo. |
AccountInactive | 401 | A conta foi desativada. | Um administrador do realm a ativa de novo. |
ClientAccessDenied | 401 | As credenciais estão certas, mas a conta não tem acesso a esta aplicação. | Dê à conta acesso ao client. |
UserSuspended | 401 | O usuário está suspenso. | Encerre a suspensão ou espere que ela termine. |
SubscriptionLapsed | 401 | A conta não tem plano ativo, então o login está pausado. | Escolha um plano para trazê-lo de volta. |
FirstPurchasePending | 401 | A conta foi criada num plano pago que nunca foi pago. | Conclua o pagamento. |
DuplicateUserName, DuplicateEmail | 409 | O usuário ou o e-mail já está em uso. | Use outro. |
Realms e clients
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
NotFound | 404 | O realm ou o client não existe, ou pertence a outra conta. | Confira o ID do realm e o ID do client. |
AlreadyExists | 409 | Já existe um realm ou client com esse ID. | Escolha outro ID, ou leia o existente. |
Inactive | 403 | O realm ou o client está desativado. | Ative-o de novo. |
Reserved | 409 | O ID é reservado: authio, system, platform, admin, master e internal não podem ser usados. | Escolha outro ID. |
SystemProtected | 403 | O realm e o client da própria plataforma não podem sair de serviço. | Mantenha-os ativos. |
InconsistentConfiguration | 400 | A configuração do client se contradiz e impediria o login. | Corrija as configurações apontadas em notifications. |
PublicClientHasNoSecret | 400 | Um client público não tem segredo para rotacionar. | Torne o client confidencial antes, se ele precisar de um segredo. |
Tokens e autorização
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
InvalidClientCredentials | 401 | O segredo do client está errado, ou foi enviado por um método para o qual o client não está registrado. | Confira o segredo e o método de autenticação no client. |
GrantTypeDisabled | 400 | O grant não está habilitado no client. | Habilite-o no client. |
InvalidRedirectUri | 400 | O redirect_uri não é igual a nenhum dos registrados. | Registre o endereço exato: esquema, host, porta, caminho e query. |
InvalidScope | 400 | Um escopo pedido não está habilitado no client. | Habilite-o, ou deixe de pedi-lo. |
MissingCodeChallenge | 400 | O client exige PKCE e o pedido não trouxe code_challenge. | Envie code_challenge e code_challenge_method. |
PkceMethodNotAllowed | 400 | O code_challenge_method não está habilitado no client. | Use S256, ou habilite o método. |
InvalidCodeVerifier | 400 | O code_verifier não corresponde ao challenge. | Envie o verifier a partir do qual o challenge foi feito. |
AuthorizationCodeExpired | 400 | O código vale 30 segundos e foi trocado tarde demais. | Troque o código assim que ele chegar. |
UnsupportedGrantType | 400 | O grant_type não é um que o Authio emite. | Use um dos grants aceitos. |
InvalidTarget | 400 | O resource não é um servidor de recurso que o client pode alcançar. | Dê ao client acesso ao servidor de recurso. |
Plano e cobrança
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
RealmLimitExceeded, ClientLimitExceeded, UserLimitExceeded, ConsumerLimitExceeded, SecretLimitExceeded, ResourceServerLimitExceeded | 400 | A cota do plano para esse recurso acabou. | Remova o que não usa mais, ou mude para um plano maior. |
SeatLimitExceeded | 402 | Todos os assentos da equipe estão ocupados. | Libere um assento ou adicione assentos. |
NoActiveSubscription | 400 | A conta não tem assinatura ativa. | Assine um plano para criar realms ou clients. |
AccountNotEntitled | 403 | A assinatura por trás da aplicação não está ativa, então o login e a emissão de tokens estão pausados. | Renove a assinatura. |
McpIntegrationNotIncluded, ConnectedAccountsNotIncluded | 403 | O plano não inclui tokens MCP ou contas conectadas. | Mude para um plano que os inclua. |
AuthLayoutNotIncluded | 403 | Personalizar as telas de login não está incluído no plano. | Mude para um plano que inclua. |
SharedTenancyNotIncluded | 403 | A conta está no plano Dedicado, então realms e clients não são criados na plataforma compartilhada. | Crie-os no console do próprio ambiente. |
Consultor de IA
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
AiAdvisorNotIncludedInPlan | 403 | O consultor de IA não está incluído no plano. | Mude para um plano que o inclua. |
AiAdvisorNotEnabled | 409 | O consultor não está ligado para este realm ou client. | Ligue-o para esse realm ou client. |
AiAdvisorRequiresAccountOperator | 403 | Só uma pessoa conectada ao console pode usar o consultor; credenciais de máquina, como chaves de API, não podem. | Chame a partir de uma sessão conectada. |
AiAdvisorNotConfigured | 503 | O consultor não está disponível nesta implantação. | Num ambiente dedicado, defina ANTHROPIC_API_KEY em Configuração. |
AiAnalysisAlreadyRunning, AiConfigurationAlreadyRunning, AiAccessReviewAlreadyRunning, AiDashboardSummaryAlreadyRunning | 409 | A mesma leitura já está sendo produzida. | Espere terminar antes de pedir de novo. |
AiConfigurationNotActionable | 409 | A proposta não está num estado que permita isso: não traz alterações, já foi aplicada ou nunca foi aplicada. | Recarregue a proposta. |
AiConfigurationStale | 409 | O client mudou depois que a proposta foi feita, então aplicá-la desfaria essa mudança. | Peça uma proposta nova. |
AiAccessReviewPeriodInvalid | 400 | O período precisa durar no mínimo uma hora e no máximo 90 dias, e terminar no máximo agora. | Escolha um período dentro desses limites. |
AiTokenShapeCarriesToken | 400 | O formato de token enviado para análise traz o próprio token. | Envie o formato do token sem o token. |
AiRunLimitExceeded | 400 | As execuções de IA do plano para o período acabaram. | Espere a contagem recomeçar, ou mude para um plano maior. |
Ambiente dedicado
| Código | HTTP | O que significa | O que fazer |
|---|---|---|---|
DedicatedInstanceNotFound | 404 | A conta ainda não tem ambiente. | Ele é preparado assim que a assinatura é confirmada. |
DedicatedInstanceNotReady | 409 | O ambiente não está rodando, então não pode ser alterado. | Tente de novo quando ele estiver pronto. |
DedicatedSubscriptionMissing | 409 | Nenhuma assinatura Dedicada ativa cobre a conta. | Assine o plano Dedicado. |
DedicatedVariableNotEditable | 400 | A variável é administrada pela plataforma. | Altere só as variáveis listadas em Configuração. |
DedicatedAdminCredentialUnavailable | 409 | A senha do primeiro administrador já foi mostrada e não é mais guardada. | Use a recuperação de senha na tela de login do seu ambiente. |
DedicatedDomainInvalid | 400 | Os nomes de host não podem ser usados: são inválidos, iguais, não ficam sob o mesmo domínio ou ficam sob o domínio da plataforma. | Use dois nomes de host seus sob um mesmo domínio. |
DedicatedDomainAlreadySet | 409 | O ambiente já tem um domínio próprio. | Remova-o antes de adicionar outro. |
DedicatedDomainNotReady | 409 | Os certificados do domínio ainda não foram emitidos. | Confira os registros DNS e tente de novo em alguns minutos. |
DedicatedServiceNotRunning | 409 | O serviço não tem um deploy em execução. | Refaça o deploy para iniciá-lo. |
DedicatedDeploymentNotFound | 404 | O deploy não é um dos deploys recentes do ambiente. | Recarregue os serviços e escolha-o de novo. |
DedicatedDeploymentNotCancellable | 409 | Só um deploy ainda sendo compilado ou implantado pode ser cancelado. | Não há o que cancelar; refaça o deploy se precisar. |
DedicatedInstanceRemovalFailed | 502 | O provedor de hospedagem não terminou de remover o ambiente. | Remova de novo; a remoção continua de onde parou. |
Próximos passos
API administrativaAutenticação, o envelope, paginação e limites de taxa.Endpoints OpenID ConnectTodos os endpoints de protocolo de um realm e os parâmetros deles.Políticas de segurançaBloqueio, expiração de senha e as regras por trás dos erros de login.Planos e cobrançaCotas, assentos e o que cada plano inclui.