Limits and errors

Limits

What	Limit
Requests per minute, per organization	120
Requests per day, per organization	10,000
Private apps per organization	5
Webhooks per organization	20
Request size	256 KB

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Over the limit, the response is 429 with Retry-After: wait that many seconds and try again.

Lists and pagination

Lists that grow with use (contacts, cards, notes) return 25 per page by default, up to 100 with limit. To continue, send the response’s nextCursor as cursor:

{
  "data": [ … ],
  "nextCursor": "MjAyNi0xMS0xMFQxNTowNDowNS4xMjNafDBiOGYz…"
}

No nextCursor means you reached the end. Lists that are small by nature (pipelines, users, custom fields) come complete in data.

Retry without duplicates

Send the Idempotency-Key header on POST requests that create something. If you repeat the same request with the same key, you get the same response and nothing is created twice: useful when you don’t know whether the first attempt went through. Keys last 24 hours.

curl -X POST https://api.meruma.app/v1/contacts/upsert \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 7f9c0d2e-order-1043" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Smith","email":"john@company.com"}'

Errors

Error responses use application/problem+json, with a stable code for your code and a title for people:

{
  "type": "about:blank",
  "title": "Name is required.",
  "status": 400,
  "code": "INVALID_BODY",
  "detail": "Field: name."
}

Some common codes: INVALID_BODY, NOT_FOUND, INSUFFICIENT_SCOPE and INVALID_TOKEN. An id from another organization always returns 404: the API never reveals whether it exists elsewhere.