Formato da Resposta

Tipo de conteúdo

Todo endpoint retorna application/json codificado em UTF-8, independentemente do cabeçalho Accept. Envie Content-Type: application/json nas requisições que carregam corpo.

Duas formas, de propósito

Endpoints de coleção envolvem seu payload em data; endpoints de objeto único retornam seus campos no nível superior. Isso não é acidente, e vale saber antes de escrever um parser:

{ "data": [ { "id": 47, "slug": "wavalid-realtime" } ] }

{ "balance": "5.230000" }

GET /v1/products é o caso de coleção; GET /v1/balance e GET /v1/api-key são o caso de objeto único. Os endpoints de tempo real retornam o próprio objeto da chamada — request_id, status, results — no nível superior.

Erros

Os erros usam um objeto fixo de dois campos:

{
  "code": "invalid_realtime_request",
  "message": "A realtime request cannot mix phone and email products."
}

Campo	Significado
code	Um identificador estável, legível por máquina. Faça o desvio com base nele.
message	Detalhe legível por humanos. O texto pode mudar; não faça parsing dele.

Os valores de code são documentados por endpoint, junto com o status HTTP com que chegam — consulte Códigos de erro para a lista completa.

Dinheiro

O dinheiro aparece em duas formas, e a diferença importa na hora de fazer o parsing:

Onde	Tipo	Exemplo
balance em GET /v1/balance	string	"5.230000"
total_charged, charged_amount, refunded_amount nas respostas de tempo real	number	0.004000

O saldo é emitido como string decimal de precisão fixa, para que nenhum cliente veja um artefato de arredondamento em um valor que está prestes a comparar com um limite. Os valores de tempo real são números arredondados para seis casas decimais — trate-os como aproximados além de seis decimais.

Os valores estão em USD. O símbolo da moeda não é incluído no payload.

Datas e horas

As datas e horas seguem ISO 8601 em UTC, com sufixo Z:

2026-09-13T10:00:00Z

checked_at em um resultado de tempo real, e as datas e horas das tarefas nas respostas em lote, seguem esse formato.

O status HTTP não é o resultado

Existem dois padrões e ambos são intencionais:

• Tempo real: HTTP 200 significa que a chamada foi executada, não que todo produto respondeu. Leia status e o billing_status de cada entrada.
• Em lote: um envio retorna o aceite da tarefa no estilo 202; o trabalho continua de forma assíncrona e o resultado só existe quando a tarefa atinge um status terminal.

A regra nos dois casos: o código de status diz se você deve tentar de novo, o corpo diz o que aconteceu.

A seguir

• Códigos de erro — cada code, por endpoint
• Limites de taxa — os cabeçalhos que retornam com 429