Límites y errores

Límites

Qué	Límite
Pedidos por minuto, por organización	120
Pedidos por día, por organización	10.000
Apps privadas por organización	5
Webhooks por organización	20
Tamaño de un pedido	256 KB

Cada respuesta trae RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Si te pasas, la respuesta es 429 con Retry-After: espera esos segundos y vuelve a intentar.

Listas y paginación

Las listas que crecen con el uso (contactos, fichas, notas) traen 25 por página por defecto, hasta 100 con limit. Para seguir, manda el nextCursor de la respuesta como cursor:

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

Sin nextCursor, llegaste al final. Las listas acotadas por naturaleza (procesos, usuarios, campos personalizados) vienen completas en data.

Reintentar sin duplicar

Manda el encabezado Idempotency-Key en los POST que crean. Si repites el mismo pedido con la misma clave, recibes la misma respuesta y no se crea nada dos veces: sirve cuando no sabes si el primer intento llegó. Las claves duran 24 horas.

curl -X POST https://api.meruma.app/v1/contacts/upsert \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 7f9c0d2e-pedido-1043" \
  -H "Content-Type: application/json" \
  -d '{"name":"Juan Pérez","email":"juan@empresa.com"}'

Errores

Las respuestas de error usan application/problem+json, con un code estable para tu código y un title en inglés para las personas:

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

Algunos códigos frecuentes: INVALID_BODY, NOT_FOUND, INSUFFICIENT_SCOPE e INVALID_TOKEN. Un id de otra organización siempre da 404: la API nunca dice si existe en otra parte.