Guia de erros

Cada código devolvido pela API, o estado correspondente no SDK e o que o plugin deve fazer.

Esta tabela é gerada a partir do código

Os códigos vêm de LICENSING_ERRORS, o mesmo enum que a API usa. Um código novo aparece aqui sozinho; um removido some. É o que impede este guia de divergir do que o servidor realmente responde.

A recusa que não ensina

Um único código cobre três situações diferentes — e isso é deliberado.

Código	HTTP	LicenseState	O que fazer
`license_not_valid`	403	INVALID	Confira se a chave no config.yml está completa e se o productId do código é o certo. Esta resposta é a mesma para chave inexistente, de outro produto e segredo errado.

license_not_valid responde a: chave inexistente, chave de outro produto, e segredo errado. Os três devolvem o mesmo corpo e o mesmo status.

Distingui-los transformaria a rota em um oráculo: bastaria testar chaves até alguma responder “existe, mas é de outro produto” para descobrir chaves válidas e mapear quais plugins elas abrem.

Diagnóstico — depois de provar a chave

Deste ponto em diante, quem pergunta já provou conhecer a chave. Esconder o motivo aqui só faria o administrador legítimo abrir um chamado para descobrir que a licença venceu ontem.

Código	HTTP	LicenseState	O que fazer
`license_expired`	403	EXPIRED	Desligue os recursos. Avise o administrador com o caminho para renovar.
`license_revoked`	403	REVOKED	Desligue os recursos. O SDK também apaga a autorização guardada, para que o modo offline não mantenha uma licença revogada viva.
`license_suspended`	403	SUSPENDED	Desligue os recursos. É reversível: oriente o administrador a falar com o vendedor.
`installation_limit_reached`	409	LIMIT_REACHED	Diga ao administrador para liberar uma instalação em /dashboard/licenses e reiniciar.
`installation_not_found`	404	RELEASED	A instalação não está registrada. Chame activate em vez de validate — isso acontece quando o arquivo de estado local foi apagado.
`installation_released`	403	RELEASED	Alguém desvinculou este servidor. Reiniciar reativa, se a política permitir reativação.
`installation_blocked`	403	RELEASED	Bloqueio administrativo. Não reativa sozinho; o administrador precisa falar com o vendedor ou com a plataforma.
`binding_mismatch`	403	BINDING_MISMATCH	O endereço mudou e a licença está vinculada a um endereço fixo. Avise que é preciso liberar a instalação no painel.
`session_expired`	403	ERROR	Chame activate de novo para obter uma sessão nova. O SDK faz isso sozinho.
`session_not_found`	404	ERROR	A sessão não existe mais. Reative.
`plugin_unavailable`	403	INVALID	O vendedor pausou ou arquivou o plugin. Licenças já instaladas continuam renovando; ativações novas, não.
`test_license_in_production`	403	INVALID	Uma chave do Playground chegou a um servidor de produção. Entregue ao cliente uma chave de verdade.

Protocolo e credencial

Código	HTTP	LicenseState	O que fazer
`bad_request`	400	ERROR	Corpo malformado, ou endereço obrigatório ausente quando a política vincula por IP. Veja error.details.
`unsupported_protocol`	400	ERROR	Atualize o SDK: esta versão do protocolo não é mais aceita.
`rate_limited`	429	ERROR	Respeite o cabeçalho Retry-After. O SDK já faz isso, com backoff exponencial e jitter.
`internal_error`	500	ERROR	Falha nossa. Tente de novo; o SDK já reitera com backoff. Se persistir, abra um chamado.
`service_unavailable`	503	GRACE	Indisponibilidade nossa. O SDK cai para a autorização guardada e o plugin CONTINUA funcionando.
`unauthorized`	401	—	Credencial ausente, inválida, revogada ou expirada. Os quatro casos respondem igual.
`forbidden`	403	—	A credencial é válida, mas não tem permissão para este recurso.
`insufficient_scope`	403	—	A chave de API não tem o escopo necessário. Crie outra com o escopo certo.
`not_found`	404	—	Recurso inexistente, ou de outra conta. Responder 404 em vez de 403 é deliberado.
`conflict`	409	—	O recurso já existe ou está em outro estado. Veja error.details.

Limites de plano

Estes atingem o vendedor, não o comprador. Nenhum deles derruba licença de cliente: eles bloqueiam a criação de recursos novos.

Código	HTTP	LicenseState	O que fazer
`plan_limit_plugins`	403	—	Limite de plugins do plano do vendedor. Arquive um ou mude de plano.
`plan_limit_licenses`	403	—	Limite de licenças ativas do plano. Revogue as inativas ou mude de plano.
`plan_limit_webhooks`	403	—	Limite de webhooks do plano.
`plan_limit_api_keys`	403	—	Limite de chaves de API do plano.
`plan_quota_exceeded`	429	—	Cota mensal excedida. Bloqueia criação, nunca a validação dos clientes.
`plan_feature_unavailable`	403	—	O recurso não está no plano atual, ou a assinatura não está em dia.

Tratando no plugin

Decida pelo code, nunca pela mensagem

O code é contrato e nunca muda. A message é texto para humano, está em português e pode ser reescrita a qualquer momento.

O Playground produz cada um destes erros contra o serviço real, com a resposta completa e a orientação correspondente — é a forma mais rápida de conferir que o seu plugin trata todos.