Erro 401 e 403 em APIs PHP: por que isso confunde tanto?

Em APIs REST feitas em PHP, os erros 401 Unauthorized e 403 Forbidden são extremamente comuns — e também extremamente mal utilizados.

Apesar de parecidos, eles têm significados completamente diferentes. Usar o código errado prejudica:

• debug
• segurança
• experiência do front-end
• integrações externas

Diferença direta: 401 vs 403

Erro 401 Unauthorized (mais comum)

O erro 401 indica que a requisição não possui credenciais válidas.

Causas comuns

• Header Authorization não enviado
• Bearer Token inválido
• Token expirado
• Token mal formatado

Exemplo de erro 401 em PHP

 'Token não informado']);
  exit;
}

Exemplo correto (Bearer Token)

 'Token inválido']);
  exit;
}

$token = trim($matches[1]);
// validar token no banco ou JWT

Erro 403 Forbidden (muito usado errado)

O erro 403 significa que o usuário está autenticado, mas não tem permissão para acessar aquele recurso.

Causas comuns

• Usuário sem perfil adequado
• Role inválida (ex: user tentando acessar admin)
• Recurso bloqueado por regra de negócio

Exemplo correto de erro 403

 'Acesso negado']);
  exit;
}

Fluxo correto de validação em APIs PHP

Siga sempre esta ordem:

1. Validar token → 401
2. Validar permissões → 403
3. Executar ação