# 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](https://docs.salchimail.com/es/creditos.md) |
| 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`](https://docs.salchimail.com/es/idempotencia.md) |
| `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](https://docs.salchimail.com/es/veredictos.md).
