Formato de Respuesta

Tipo de contenido

Todos los endpoints devuelven application/json codificado en UTF-8, sin importar el encabezado Accept. Envía Content-Type: application/json en las solicitudes que llevan cuerpo.

Dos formas, a propósito

Los endpoints de colección envuelven su payload en data; los endpoints de objeto único devuelven sus campos en el nivel superior. No es una casualidad, y conviene saberlo antes de escribir un parser:

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

{ "balance": "5.230000" }

GET /v1/products es el caso de colección; GET /v1/balance y GET /v1/api-key son el caso de objeto único. Los endpoints en tiempo real devuelven el objeto propio de la llamada — request_id, status, results — en el nivel superior.

Errores

Los errores usan un objeto fijo de dos campos:

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

Campo	Significado
code	Un identificador estable legible por máquina. Bifurca según este valor.
message	Detalle legible por humanos. El texto puede cambiar; no lo parsees.

Los valores de code se documentan por endpoint, junto con el estado HTTP con el que llegan — consulta Códigos de error para ver la lista completa.

Dinero

El dinero aparece en dos formas, y la diferencia importa cuando parseas:

Dónde	Tipo	Ejemplo
balance en GET /v1/balance	string	"5.230000"
total_charged, charged_amount, refunded_amount en las respuestas en tiempo real	number	0.004000

El saldo se emite como una cadena decimal de precisión fija para que ningún cliente vea un artefacto de redondeo en un valor que está a punto de comparar con un umbral. Los montos en tiempo real son números redondeados a seis decimales — trátalos como aproximados más allá de seis decimales.

Los importes están en USD. El símbolo de la moneda no se incluye en el payload.

Marcas de tiempo

Las marcas de tiempo están en ISO 8601 en UTC, con el sufijo Z:

2026-09-13T10:00:00Z

checked_at en un resultado en tiempo real, y las marcas de tiempo de tarea en las respuestas masivas, siguen este formato.

El estado HTTP no es el resultado

Existen dos patrones y ambos son intencionales:

• En tiempo real: HTTP 200 significa que la llamada se ejecutó, no que todos los productos respondieron. Lee status y el billing_status de cada entrada.
• Masivo: un envío devuelve una aceptación de tarea al estilo 202; el trabajo continúa de forma asíncrona y el resultado solo existe cuando la tarea alcanza un estado terminal.

La regla en ambos casos: el código de estado indica si debes reintentar, el cuerpo indica qué ocurrió.

Siguiente

• Códigos de error — cada code, por endpoint
• Límites de tasa — los encabezados que se devuelven con 429