# Limits and errors

## Rate limits

Limits depend on your plan. `GET /account` returns the ones that apply to your key in `limits`.

| Plan | Requests per minute | Rows per batch | Batches at once |
| --- | --- | --- | --- |
| Free | 60 | 100 | 1 |
| Basic | 600 | 100,000 | 3 |
| Basic+ | 1,200 | 100,000 | 5 |

These are the current values. `GET /account` is the source of truth.

Every response carries three headers:

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests allowed in the current window |
| `RateLimit-Remaining` | Requests left in the current window |
| `RateLimit-Reset` | Seconds until the window resets |

Over the limit the API answers `429` with a `Retry-After` header, in seconds. Wait that long and retry.

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

## Size limits

| What | Limit |
| --- | --- |
| `email` | 1,024 characters |
| Addresses in a JSON batch | 10,000 |
| JSON body | 2 MB |
| CSV file | 10 MB and 100,000 data rows |
| Batch `name` | 120 characters |
| `Idempotency-Key` | 255 characters |
| Page of batches (`limit`) | 100, default 20 |
| Page of results (`limit`) | 1,000 as JSON, 10,000 as CSV, default 100 |
| A `mailbox` verification | 30 seconds, then `503 verification_timeout` |

## The error format

Every error has the same shape:

```json
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}
```

| Field | Meaning |
| --- | --- |
| `type` | The broad class of the error |
| `code` | Stable and machine-readable. Branch on this |
| `message` | For humans. Do not parse it. English by default, Spanish with `Accept-Language: es` |
| `param` | The request field the error refers to, when there is one |
| `request_id` | Same value as the `X-Request-Id` response header. Quote it when you write to support |

New `code` values may be added without a version change. Treat a code you do not know as its `type`.

## Error codes

| HTTP | `type` | `code` | Meaning | What to do |
| --- | --- | --- | --- | --- |
| 400 | `invalid_request` | `invalid_json` | The body is not valid JSON | Fix the request |
| 400 | `invalid_request` | `missing_parameter` | A required field is missing (see `param`) | Fix the request |
| 400 | `invalid_request` | `invalid_parameter` | A field or query parameter has a value that is not accepted (see `param`) | Fix the request |
| 400 | `invalid_request` | `batch_empty` | The batch has no addresses | Send at least one |
| 400 | `invalid_request` | `batch_too_large` | More rows than your plan accepts in one batch | Split the list |
| 400 | `invalid_request` | `csv_invalid` | The file is not a readable UTF-8 CSV with a header row | Fix the file |
| 400 | `invalid_request` | `csv_column_not_found` | No header matches `email_column` | Send the exact header name |
| 401 | `authentication` | `missing_api_key` | No `Authorization: Bearer` header | Send your key |
| 401 | `authentication` | `invalid_api_key` | The key does not exist | Check the key |
| 401 | `authentication` | `revoked_api_key` | The key was revoked | Use a current key |
| 402 | `payment_required` | `insufficient_credits` | Not enough credits of the type the request needs | Top up. See [Credits and billing](https://docs.salchimail.com/credits.md) |
| 403 | `permission` | `mode_not_allowed` | The account may not use that `mode` | Check `limits.modes` in `GET /account` |
| 403 | `permission` | `account_suspended` | The account is suspended | Write to support |
| 404 | `not_found` | `not_found` | The resource does not exist, belongs to another account or has expired | Check the identifier |
| 409 | `conflict` | `idempotency_key_reused` | Same `Idempotency-Key`, different body | Use a new key |
| 409 | `conflict` | `idempotency_in_progress` | The first request with that key is still running | Wait and retry |
| 409 | `conflict` | `batch_not_cancelable` | The batch is already `completed` or `failed` | Nothing to cancel |
| 413 | `invalid_request` | `payload_too_large` | The body is over 2 MB (JSON) or 10 MB (CSV) | Split the list |
| 415 | `invalid_request` | `unsupported_media_type` | Wrong `Content-Type` | Use `application/json`, or `multipart/form-data` for CSV batches |
| 429 | `rate_limit` | `rate_limit_exceeded` | Too many requests | Wait `Retry-After` seconds |
| 429 | `rate_limit` | `concurrent_batches_exceeded` | Too many batches running at once | Wait for one to finish |
| 500 | `api_error` | `internal_error` | Unexpected error on our side | Retry with the same `Idempotency-Key` |
| 503 | `api_error` | `engine_unavailable` | The verification engine is unavailable. Nothing was charged | Retry later |
| 503 | `api_error` | `verification_timeout` | The check did not finish in time. Nothing was charged | Retry later, or use a batch |

## What to retry

| Answer | Retry? |
| --- | --- |
| Network error or timeout | Yes, with the same [`Idempotency-Key`](https://docs.salchimail.com/idempotency.md) |
| `429` | Yes, after `Retry-After` |
| `500`, `503` | Yes, with an increasing wait between attempts |
| `409 idempotency_in_progress` | Yes, after a short wait |
| `400`, `401`, `402`, `403`, `404`, `413`, `415` | No. The answer will not change until the request or the account changes |

Double the wait after each failed attempt and stop after a few. An error never charges credits.

A verification that answers `200` with verdict `unknown` is not an error: see [Verdicts and reason codes](https://docs.salchimail.com/verdicts.md).
