Rate limits & errors

Rate limits

The default limit is 100 requests per minute, tracked per IP address. It applies globally across endpoints: there's no separate budget for reads versus writes, and no per-endpoint override right now.

Go over the limit and you'll get a 429:

{
  "type": "https://peleka.io/errors/429",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded",
  "instance": "/api/v1/contacts"
}

There's no Retry-After header on this response yet, so back off with a fixed interval (a couple of seconds is enough for a normal integration) rather than retrying immediately in a loop. If your integration is syncing a large batch of contacts, batch endpoints exist for this reason: use them instead of looping single-record calls, both to stay under the limit and because they're just faster.

Error format

Every error, regardless of status code, follows RFC 7807:

{
  "type": "https://peleka.io/errors/{status}",
  "title": "Short, human-readable summary",
  "status": 422,
  "detail": "What specifically went wrong",
  "instance": "/api/v1/contacts"
}

type is a stable URL you can match against in code. It won't change even if the wording of title or detail does. Some errors add extra fields alongside these four (a validation error might include a fields array pointing at which inputs failed); anything beyond the base four is endpoint-specific, so check the reference page for the endpoint you're calling.

Status codes you'll actually see

A 409 on contact creation is worth planning around explicitly: Peleka doesn't silently upsert on duplicate email. See Syncing contacts for the create-then-update pattern this implies.