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.
{
"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:
{
"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.