Mensagens de Erro

Todas as respostas de erro seguem o envelope padrão com um objeto errors estruturado. Os códigos de erro usam o formato MIDDAG-{DOMAIN}-{CODE} para erros específicos de domínio e códigos padrão da API para erros de transporte.

Códigos de Erro da API

Esses códigos aparecem no campo errors.code de qualquer resposta de erro:

Código	HTTP	Quando	Exemplo de Detalhe
VALIDATION_ERROR	422	Campos de entrada inválidos	"Email is required"
AUTHENTICATION_ERROR	401	Token ausente, expirado ou inválido	"Token expired"
AUTHORIZATION_ERROR	403	Permissões insuficientes	"Scope 'finances' required"
NOT_FOUND	404	Recurso não existe	"Organization 42 not found"
CONFLICT	409	Estado conflitante	"Entitlement already cancelled"
RATE_LIMIT	429	Limite de requisições excedido	"5 requests/min exceeded"
INTERNAL_ERROR	500	Erro inesperado no servidor	"Unexpected error"

Estrutura da Resposta de Erro

{
    "success": false,
    "data": null,
    "meta": null,
    "message": "Validation failed",
    "errors": {
        "code": "VALIDATION_ERROR",
        "fields": {
            "email": [
                "Email is required"
            ],
            "name": [
                "Name must be at least 2 characters"
            ]
        }
    }
}

Para erros que não são de válidação, o objeto errors usa detail em vez de fields:

{
    "success": false,
    "data": null,
    "meta": null,
    "message": "Authentication failed",
    "errors": {
        "code": "AUTHENTICATION_ERROR",
        "detail": "Token expired"
    }
}

Códigos de Erro Específicos de Domínio

Erros de Organization

Código	HTTP	Descrição
MIDDAG-ORG-NOT_FOUND	404	A organização não existe
MIDDAG-ORG-CNPJ_INVALID	422	CNPJ falhou na válidação da API federal
MIDDAG-ORG-CNPJ_DUPLICATE	409	CNPJ já registrado em outra organização
MIDDAG-ORG-DELETE_DENIED	403	Somente o proprietário pode excluir a organização

Erros de Collaborator

Código	HTTP	Descrição
MIDDAG-COLLAB-NOT_FOUND	404	Registro de colaborador não encontrado
MIDDAG-COLLAB-INVITE_EXPIRED	409	Token de convite expirou
MIDDAG-COLLAB-INVITE_USED	409	Convite já aceito ou rejeitado
MIDDAG-COLLAB-ALREADY_MEMBER	409	O usuário já é um colaborador
MIDDAG-COLLAB-ROLE_ESCALATION	403	Não é possível atribuir um cargo superior ao seu

Erros de Entitlement

Código	HTTP	Descrição
MIDDAG-ENT-NOT_FOUND	404	O entitlement não existe
MIDDAG-ENT-ALREADY_CANCELLED	409	O entitlement já está cancelado
MIDDAG-ENT-INVALID_TRANSITION	422	A transição de status não é permitida
MIDDAG-ENT-INVALID_CLASS	422	A classe do entitlement não é reconhecida

Erros de Quote

Código	HTTP	Descrição
MIDDAG-QUOTE-NOT_FOUND	404	O quote não existe
MIDDAG-QUOTE-ALREADY_ACCEPTED	409	O quote já foi aceito
MIDDAG-QUOTE-EXPIRED	409	O período de validade do quote passou
MIDDAG-QUOTE-INVALID_TRANSITION	422	A transição de status não é permitida

Erros de License

Código	HTTP	Descrição
MIDDAG-LIC-NOT_FOUND	404	A licença não existe
MIDDAG-LIC-UNAVAILABLE	503	O sistema de licenças não está disponível
MIDDAG-LIC-ACTIVATION_LIMIT	409	Número máximo de ativações atingido
MIDDAG-LIC-DOMAIN_REQUIRED	422	O parâmetro domain é obrigatório
MIDDAG-LIC-DOMAIN_NOT_ACTIVE	409	O domínio não está ativado atualmente

Erros de Service

Código	HTTP	Descrição
MIDDAG-SVC-NOT_FOUND	404	O serviço não existe
MIDDAG-SVC-INVALID_TRANSITION	422	A transição de status não é permitida

Erros de Ticket

Código	HTTP	Descrição
MIDDAG-SR-NOT_FOUND	404	A solicitação de serviço não existe
MIDDAG-SR-INVALID_TRANSITION	422	A transição de status não é permitida
MIDDAG-SR-ENV_ONLY	403	Clientes só podem criar SRs para entitlements do tipo ENV

Erros de Autenticação

Código	HTTP	Descrição
MIDDAG-AUTH-INVALID_CREDS	401	E-mail ou senha inválidos
MIDDAG-AUTH-TOKEN_EXPIRED	401	O JWT expirou
MIDDAG-AUTH-TOKEN_REVOKED	401	Token revogado por logout
MIDDAG-AUTH-EMAIL_UNVERIFIED	403	E-mail ainda não verificado
MIDDAG-AUTH-ACCOUNT_DISABLED	403	A conta foi desabilitada
MIDDAG-AUTH-RATE_LIMITED	429	Muitas tentativas de autenticação

Tratamento de Erros no Código Cliente

const response = await fetch('/wp-json/middag-account/v1/entitlements', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'X-Middag-Organization': orgId,
  },
});

const body = await response.json();

if (!body.success) {
  if (body.errors.code === 'AUTHENTICATION_ERROR') {
    // Redirecionar para login ou atualizar token
  } else if (body.errors.code === 'VALIDATION_ERROR') {
    // Exibir erros por campo de body.errors.fields
  }
}

Relacionados

• Visão Geral da REST API -- Códigos de erro e formato de envelope
• Labels de Status -- Valores de status válidos para evitar erros CONFLICT