Erros

Erro tem contrato. O código HTTP e o campo code são estáveis: trate por eles, nunca pelo texto de message, que pode mudar.

{
  "error": {
    "code": "documento_invalido",
    "message": "CPF inválido."
  }
}

Códigos

HTTP	code	O que aconteceu	O que fazer
401	token_invalido	Token ausente, inválido ou expirado	Confira o cabeçalho e o token
402	sem_saldo	Saldo abaixo do preço da consulta	Adicione saldo
403	escopo_insuficiente	O token não tem o escopo da operação	Crie um token com o escopo certo
403	conta_inativa	Conta suspensa ou inativa	Fale com o suporte
403	bloqueado	Acesso bloqueado, por exemplo IP fora da lista do token	Confira os endereços permitidos
404	servico_indisponivel	A consulta não existe ou não está liberada para a conta	Confira o identificador no catálogo
404	sem_dados	Documento válido, mas sem registro para ele	Trate como resposta negativa, não como falha
409	idempotency_conflito	A chave de idempotência já foi usada em outra consulta	Use uma chave nova por operação
409	idempotency_em_processamento	A consulta com essa chave ainda está rodando	Espere e repita
422	documento_invalido	CPF ou CNPJ não passa na validação	Corrija antes de reenviar
422	entrada_invalida	Falta ou está errado um campo da consulta	Veja campos na resposta
429	rate_limit	Chamadas demais por segundo	Espere e repita com recuo
429	teto_excedido	O token atingiu o teto de gasto	Ajuste o teto no painel
500	erro_interno	Falha nossa ao processar	Repita; se persistir, avise o suporte
502	falha_fornecedor	A origem do dado recusou a consulta	Repita mais tarde
502	payload_incompativel	A origem respondeu sem dado utilizável	Repita mais tarde
503	fornecedor_offline	A origem do dado está fora do ar	Repita com recuo
504	fornecedor_timeout	A origem do dado não respondeu a tempo	Repita com recuo

Em entrada_invalida, a resposta traz também campos, com o motivo de cada campo recusado:

{
  "error": {
    "code": "entrada_invalida",
    "message": "Confira os campos enviados.",
    "campos": { "selfie_img": "é obrigatório" }
  }
}

Consulta que falha não é cobrada

Nenhum dos erros acima debita saldo, incluindo o sem_dados. A cobrança só acontece quando a consulta é concluída com sucesso.

Repetir com recuo

Para 429, 503 e 504, repita com intervalo crescente em vez de insistir. Mande sempre a mesma Idempotency-Key nas repetições: se a primeira tentativa tiver chegado ao fim do nosso lado, você recebe aquele resultado e não paga de novo.

async function consultarComRecuo(slug, corpo, tentativas = 3) {
  const chave = crypto.randomUUID()

  for (let i = 0; i < tentativas; i++) {
    const resposta = await fetch(`https://api.radardata.com.br/api/v2/${slug}`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.RADARDATA_TOKEN}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': chave,
      },
      body: JSON.stringify(corpo),
    })

    if (![429, 503, 504].includes(resposta.status)) return resposta

    // 1s, 2s, 4s
    await new Promise((ok) => setTimeout(ok, 2 ** i * 1000))
  }

  throw new Error('A consulta seguiu indisponível depois de 3 tentativas.')
}

Não repita em 401, 402, 403 ou 422: o resultado seria o mesmo.