json_decode retornando null: achar o erro com JSON_THROW_ON_ERROR

A API respondeu 200, você jogou o corpo no json_decode() e recebeu null. Nenhum warning, nenhuma exception, nenhuma pista. O json_decode() é silencioso por padrão: quando o JSON está quebrado ele devolve null e guarda o motivo num canto que quase ninguém consulta.

Primeiro: pergunte o motivo

Antes de sair mexendo no endpoint, leia o erro que o PHP já tem guardado:

$dados = json_decode($resposta, true);

if ($dados === null && json_last_error() !== JSON_ERROR_NONE) {
    error_log('JSON quebrado: ' . json_last_error_msg());
    error_log('primeiros 200 bytes: ' . substr($resposta, 0, 200));
}

Repare na comparação dupla. A string null é JSON válido e decodifica para null também, então testar só === null confunde resposta vazia com resposta corrompida. Quem decide é o json_last_error().

Depois: force o PHP a gritar

No PHP 8.3 eu nem escrevo mais aquele if. Passo a flag e trato o problema como qualquer outro erro da aplicação:

try {
    $dados = json_decode($resposta, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    error_log('decode falhou: ' . $e->getMessage());
    throw new RuntimeException('Resposta inválida do fornecedor', 0, $e);
}

Detalhe que já me fez perder tempo: com JSON_THROW_ON_ERROR o json_last_error() não é atualizado, continua devolvendo o erro da chamada anterior. Escolha um dos dois estilos por fluxo, senão você loga a mensagem errada.

As três causas que mais me pegaram

BOM no começo do arquivo, quando o JSON veio de um .json salvo no Bloco de Notas. Um Warning: ... on line 12 impresso pelo servidor do outro lado antes do corpo, o clássico Syntax error. E resposta gzipada lida crua, quando o cURL rodou sem CURLOPT_ENCODING => ''.

Pro BOM a limpeza é uma linha só, antes do decode:

$resposta = preg_replace('/^xEFxBBxBF/', '', $resposta);

Sempre que aparecer Syntax error, logue o trecho bruto junto com a mensagem. Na maioria das vezes o problema está visível nos primeiros bytes e você mata a dúvida sem abrir o Postman.

Dúvidas? Faça um comentário logo abaixo ou envie uma mensagem clicando aqui.

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *