3

O ID do pedido mudou sozinho? JSON, números grandes e o limite de 2^53

Um bug clássico de integração: o backend devolve {"pedido_id": 9007199254740993}, o front exibe 9007199254740992 e ninguém entende de onde veio a diferença de 1. Não é problema de rede nem de banco. É o jeito como o JavaScript representa números.

O que acontece

O JSON, como formato, não limita o tamanho de um número. Mas quem faz o parse decide como guardar o valor. No JavaScript, JSON.parse transforma todo número em Number, que é um ponto flutuante de 64 bits (IEEE 754). Ele só representa inteiros com exatidão até 2^53 − 1, ou seja, 9007199254740991 (Number.MAX_SAFE_INTEGER). Acima disso, alguns inteiros simplesmente não existem e o valor é arredondado para o vizinho representável mais próximo.

Exemplo verificado

No Node.js (testado na v24):

const o = JSON.parse('{"pedido_id": 9007199254740993}');
console.log(o.pedido_id);          // 9007199254740992
console.log(JSON.stringify(o));    // {"pedido_id":9007199254740992}

Repare no segundo log: se esse objeto for reenviado, o ID errado vai junto e o erro se espalha.

Em Python, o json padrão usa int de precisão arbitrária, então o valor chega intacto:

import json
s = '{"pedido_id": 9007199254740993}'
print(json.loads(s)["pedido_id"])                   # 9007199254740993
print(json.loads(s, parse_int=float)["pedido_id"])  # 9007199254740992.0
print(float(2**53 + 1) == float(2**53))             # True

O parse_int=float simula o que o JavaScript faz: 2^53 + 1 e 2^53 viram o mesmo float. Por isso o mesmo JSON "funciona" no backend em Python e quebra no navegador.

Como evitar

  1. Mande IDs grandes como string. {"pedido_id": "9007199254740993"} é a solução mais portável. ID não é para fazer conta, então string é o tipo certo. Várias APIs públicas fazem isso por esse motivo.
  2. Se precisar fazer conta, use BigInt. Em runtimes recentes, o reviver do JSON.parse recebe um terceiro argumento com o texto original do número (context.source). Com isso, dá para fazer BigInt(context.source) sem perder dígitos. No Node v24 isso funcionou, mas confira o suporte no seu ambiente antes de depender disso.
  3. Teste a borda. Coloque no teste de contrato um ID maior que 9007199254740991 e verifique se ele volta idêntico depois de um ciclo parse → stringify.

Resumo

Se um inteiro pode passar de 2^53 − 1 (IDs de banco com snowflake, timestamps em nanossegundos, valores em centavos muito grandes), não confie no Number. Serialize como string ou trate com BigInt, e escreva um teste que pegue isso antes do usuário.

Carregando publicação patrocinada...