Rate limits and errors

Limits per key, response headers and error codes

​

Rate limits

Limits are counted per key, in a 60-second window.

Routes	Limit
All routes	60 requests per minute
GET .../reports/performance	10 requests per minute

Requests with an invalid key are limited per IP address: after 20 in a minute, the address gets 429 until the minute ends.

Every authenticated response includes:

Header	Description
X-RateLimit-Limit	Requests allowed in the window
X-RateLimit-Remaining	Requests left in the window
X-RateLimit-Reset	Unix timestamp when the window resets

When the limit is exceeded, the API returns 429 with Retry-After, the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1794405600

Wait for Retry-After before trying again. Requests sent during the wait also count.

Each key has its own limit. Use one key per integration so one job does not use up the limit of another.

​

Error format

Every error has the same body:

{
  "success": false,
  "message": "Insufficient scope",
  "code": "FORBIDDEN"
}

Use code and the HTTP status in your code. message is for people and can change.

​

Error codes

Status	Code	Cause	What to do
400	BAD_REQUEST	Invalid or unknown parameter, limit above 100, period longer than 90 days	Fix the request. Do not retry as is.
401	UNAUTHORIZED	Missing, invalid, expired or revoked key, or not a brand key	Check the key. Create or rotate one in the dashboard.
403	FORBIDDEN	Key of the other vertical, or without the scope of the route	Use the key of the right vertical, or create one with the scope.
404	NOT_FOUND	The resource does not exist in your program	Check the id. Ids of another brand also return 404.
429	TOO_MANY_REQUESTS	Rate limit exceeded	Wait for Retry-After.
500	INTERNAL_SERVER_ERROR	Error on Lomadee’s side	Retry with increasing waits. If it continues, contact support with the X-Request-Id.

​

Request id

Every response has an X-Request-Id header. Send it to support when you report a problem.

​

Retries

• Retry only 429 and 5xx.
• Wait 1s, 2s, 4s, 8s between attempts, with at most 5 attempts. On 429, wait for Retry-After instead.
• Every route is a GET, so repeating a request never changes data.