> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.laposta.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.laposta.org/_mcp/server.

# What are the limits and error messages of the API?

> How many requests per minute the API allows and which status and error codes may be returned.

## How many requests are you allowed to make?

The API limits the number of requests per minute per account.

| Account type | Requests per minute |
| ------------ | ------------------- |
| Free         | 30                  |
| Paid         | 120                 |

If you exceed this limit, you will receive a `429` with a header telling you how long you need to wait:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

```json
{
  "error": {
    "type": "invalid_request",
    "message": "Rate limit exceeded, try again after 60 seconds"
  }
}
```

There are no headers tracking your usage while everything is going well. Wait for the `Retry-After` and keep track of how many requests you send yourself. Also, cache data that rarely changes: you do not need to fetch the fields of a list on every page view; once a day is enough.

## What does an error message look like?

All error messages have the same structure, so you can handle them in one place. Every error is returned as JSON with a `type`, a `message`, and usually a `code` and the `parameter` that caused the error.

```json
{
  "error": {
    "type": "invalid_input",
    "message": "Email: invalid address",
    "code": 208,
    "parameter": "email"
  }
}
```

The `type` field can have three values: `invalid_request` if the call itself is incorrect, `invalid_input` if the submitted data is incorrect, and `internal` if something goes wrong on Laposta's end.

## Status codes

The API uses standard HTTP status codes to indicate how the request went.

| Code  | Meaning                                                                      |
| ----- | ---------------------------------------------------------------------------- |
| `200` | Success.                                                                     |
| `201` | Success, and something was created.                                          |
| `400` | Something is wrong with the request or the submitted data.                   |
| `401` | No valid key was provided, or this endpoint is not enabled for this account. |
| `402` | The data was correct, but the request was not executed.                      |
| `404` | This path does not exist.                                                    |
| `429` | Too many requests in a minute.                                               |
| `500` | Something went wrong on Laposta's end.                                       |

> **Warning**
>
> An object that does not exist does not return a `404`, but a `400` with error code `203`. Do not test for `404` to see if a list or subscriber exists, because you will only receive that for a path that does not exist.

## Error codes

With `invalid_input`, a numeric code is included so you can translate the error into a message for your own user. Combined with `parameter`, you know exactly which field is affected.

| Code  | Meaning                                                                                    |
| ----- | ------------------------------------------------------------------------------------------ |
| `201` | The parameter is empty.                                                                    |
| `202` | The provided value does not have the correct format.                                       |
| `203` | The provided value does not exist, for example an ID that does not belong to this account. |
| `204` | The value already exists.                                                                  |
| `205` | The value is not a number.                                                                 |
| `206` | The value is not `true` or `false`.                                                        |
| `207` | The value is not a date.                                                                   |
| `208` | The value is not an email address.                                                         |
| `209` | The value is not a URL.                                                                    |
| `210` | The value is not valid JSON.                                                               |
| `999` | Something else is wrong with the value.                                                    |

An ID from another account returns the same message as an ID that does not exist anywhere: `Unknown list`, with code `203`. This is intentional, so it is not possible to see what is in other accounts.

## Related articles

#### [What are common mistakes with the API?](/veelgemaakte-fouten-met-de-api)

Pitfalls when integrating with the Laposta API, including the error message you get and…

#### [Synchronising subscribers through the API](/relaties-synchroniseren-via-de-api)

Keep your list in sync with your webshop or CRM: adding, updating, unsubscribing and…

#### [How do date and time fields work in the API?](/api-datum-en-tijdvelden)

The API uses two formats for dates and times. Read how to retrieve and send them.