Comece pelo charset: UTF-8 nos dois lados
A causa número um de Base64 'quebrado' com texto em português é divergência de codificação de caracteres entre as pontas. Codifique e decodifique sempre em UTF-8; misturar UTF-8 de um lado com Latin-1 do outro transforma acentos e cedilhas em símbolos estranhos — e o receptor culpa o Base64 por um problema que é do charset.
Se você recebe sequências geradas por sistemas legados, descubra qual charset eles usam antes de decodificar. Perguntar leva um minuto; adivinhar e testar combinações pode levar uma tarde inteira.
Respeite o padding e a variante esperada
Os sinais de igual no fim (= ou ==) fazem parte do padrão Base64 — removê-los quando o destino os exige quebra a decodificação com erros pouco explicativos. Por outro lado, alguns sistemas no modo URL-safe dispensam o padding e até o rejeitam se ele estiver presente. A regra é simples e inegociável: siga a documentação do destino, não o seu hábito.
O mesmo vale para + e / versus - e _: trocar a variante no meio do caminho é erro clássico em integrações de API, especialmente ao copiar JWTs entre ferramentas diferentes. Confira a variante antes de qualquer outra hipótese.
Elimine ruído de cópia: espaços e quebras intrusas
Copiar sequências de PDFs, chats, e-mails e tickets costuma trazer espaços, quebras de linha e até hífens de continuação grudados no texto. Antes de decodificar algo recebido de terceiros, cole num editor de texto puro e inspecione o início e o fim da sequência — é ali que o lixo costuma se esconder.
Sequências válidas contêm apenas A–Z, a–z, 0–9, + ou / (ou - e _ na variante URL-safe) e no máximo dois sinais de igual no final. Qualquer outro caractere no meio é sinal de contaminação na cópia, não de problema no algoritmo.
Valide com o teste de ida e volta
O teste definitivo de qualidade é decodificar o resultado e comparar byte a byte com o original. Se bater exatamente, a sequência está íntegra; se não bater, o problema está na entrada, na cópia ou nas configurações — nunca 'no algoritmo', que é determinístico e idêntico em toda implementação correta.
Para dados críticos como chaves, certificados e segredos de configuração, faça esse teste sempre, sem exceção. Leva segundos e evita horas de depuração depois, quando o erro já se espalhou pelo sistema.
Perguntas frequentes
Por que o sistema diz que meu Base64 é inválido?
Na maioria das vezes, por um destes três motivos: variante errada (padrão vs URL-safe), padding removido indevidamente ou caracteres estranhos grudados na cópia. Confira nessa ordem — resolve 90% dos casos.
Acentos podem quebrar a codificação?
Só se houver divergência de charset entre a codificação e a decodificação. Mantendo UTF-8 nos dois lados, acentos, cedilha e emojis funcionam normalmente.
Quebras de linha no meio da sequência são problema?
Para decodificação, geralmente não — boas ferramentas as ignoram. Mas alguns validadores estritos rejeitam; na dúvida, trabalhe com a sequência contínua.
Como sei se a sequência está completa?
Compare o tamanho com o esperado (cerca de 4/3 do original) e faça o teste de ida e volta: decodifique e confira se o conteúdo recuperado bate com o original.