What are the limits and error messages of the API?

How many requests are you allowed to make?

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

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

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

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

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

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.

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