Límites y errores

Límites de peticiones

Los límites dependen de tu plan. GET /account devuelve en limits los que se aplican a tu clave.

Plan Peticiones por minuto Filas por lote Lotes simultáneos
Gratis 60 100 1
Básico 600 100.000 3
Básico+ 1.200 100.000 5

Estos son los valores actuales. La fuente de verdad es GET /account.

Todas las respuestas llevan tres cabeceras:

Cabecera Significado
RateLimit-Limit Peticiones permitidas en la ventana actual
RateLimit-Remaining Peticiones que quedan en la ventana actual
RateLimit-Reset Segundos hasta que se reinicia la ventana

Por encima del límite, la API responde 429 con una cabecera Retry-After, en segundos. Espera ese tiempo y reintenta.

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}

Límites de tamaño

Qué Límite
email 1.024 caracteres
Direcciones en un lote JSON 10.000
Cuerpo JSON 2 MB
Fichero CSV 10 MB y 100.000 filas de datos
name de un lote 120 caracteres
Idempotency-Key 255 caracteres
Página de lotes (limit) 100, por defecto 20
Página de resultados (limit) 1.000 en JSON, 10.000 en CSV, por defecto 100
Una verificación mailbox 30 segundos; después, 503 verification_timeout

El formato de error

Todos los errores tienen la misma forma:

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}
Campo Significado
type La clase general del error
code Estable y pensado para máquinas. Decide según este campo
message Para personas. No lo analices. En inglés por defecto; en español con Accept-Language: es
param El campo de la petición al que se refiere el error, cuando lo hay
request_id El mismo valor que la cabecera de respuesta X-Request-Id. Cítalo cuando escribas a soporte

Pueden añadirse valores nuevos de code sin cambiar de versión. Trata un código que no conozcas según su type.

Códigos de error

HTTP type code Significado Qué hacer
400 invalid_request invalid_json El cuerpo no es JSON válido Corrige la petición
400 invalid_request missing_parameter Falta un campo obligatorio (mira param) Corrige la petición
400 invalid_request invalid_parameter Un campo o parámetro tiene un valor no admitido (mira param) Corrige la petición
400 invalid_request batch_empty El lote no tiene direcciones Envía al menos una
400 invalid_request batch_too_large Más filas de las que tu plan acepta en un lote Divide la lista
400 invalid_request csv_invalid El fichero no es un CSV legible en UTF-8 con fila de cabecera Corrige el fichero
400 invalid_request csv_column_not_found Ninguna cabecera coincide con email_column Envía el nombre exacto de la cabecera
401 authentication missing_api_key Falta la cabecera Authorization: Bearer Envía tu clave
401 authentication invalid_api_key La clave no existe Revisa la clave
401 authentication revoked_api_key La clave se revocó Usa una clave vigente
402 payment_required insufficient_credits No hay créditos suficientes del tipo que necesita la petición Recarga. Consulta Créditos y facturación
403 permission mode_not_allowed La cuenta no puede usar ese mode Consulta limits.modes en GET /account
403 permission account_suspended La cuenta está suspendida Escribe a soporte
404 not_found not_found El recurso no existe, es de otra cuenta o ha caducado Revisa el identificador
409 conflict idempotency_key_reused Misma Idempotency-Key, cuerpo distinto Usa una clave nueva
409 conflict idempotency_in_progress La primera petición con esa clave sigue en curso Espera y reintenta
409 conflict batch_not_cancelable El lote ya está completed o failed No hay nada que cancelar
413 invalid_request payload_too_large El cuerpo supera 2 MB (JSON) o 10 MB (CSV) Divide la lista
415 invalid_request unsupported_media_type Content-Type incorrecto Usa application/json, o multipart/form-data para lotes CSV
429 rate_limit rate_limit_exceeded Demasiadas peticiones Espera los segundos de Retry-After
429 rate_limit concurrent_batches_exceeded Demasiados lotes en curso a la vez Espera a que termine uno
500 api_error internal_error Error inesperado por nuestra parte Reintenta con la misma Idempotency-Key
503 api_error engine_unavailable El motor de verificación no está disponible. No se cobró nada Reintenta más tarde
503 api_error verification_timeout La comprobación no terminó a tiempo. No se cobró nada Reintenta más tarde o usa un lote

Qué reintentar

Respuesta ¿Reintentar?
Error de red o tiempo de espera agotado Sí, con la misma Idempotency-Key
429 Sí, después de Retry-After
500, 503 Sí, con una espera creciente entre intentos
409 idempotency_in_progress Sí, tras una espera corta
400, 401, 402, 403, 404, 413, 415 No. La respuesta no cambiará hasta que cambie la petición o la cuenta

Duplica la espera tras cada intento fallido y para después de unos pocos. Un error nunca cobra créditos.

Una verificación que responde 200 con veredicto unknown no es un error: consulta Veredictos y reason codes.

Ver esta página en Markdown