Limites e erros

Limites

O quê	Limite
Requisições por minuto, por organização	120
Requisições por dia, por organização	10.000
Apps privados por organização	5
Webhooks por organização	20
Tamanho de uma requisição	256 KB

Cada resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Acima do limite, a resposta é 429 com Retry-After: espere esses segundos e tente de novo.

Listas e paginação

As listas que crescem com o uso (contatos, fichas, notas) trazem 25 por página por padrão, até 100 com limit. Para continuar, envie o nextCursor da resposta como cursor:

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

Sem nextCursor, você chegou ao fim. As listas pequenas por natureza (processos, usuários, campos personalizados) vêm completas em data.

Tentar de novo sem duplicar

Envie o cabeçalho Idempotency-Key nos POST que criam algo. Se você repetir a mesma requisição com a mesma chave, recebe a mesma resposta e nada é criado duas vezes: serve quando você não sabe se a primeira tentativa chegou. As chaves duram 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":"João Silva","email":"joao@empresa.com"}'

Erros

As respostas de erro usam application/problem+json, com um code estável para o seu código e um title em inglês para as pessoas:

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

Alguns códigos frequentes: INVALID_BODY, NOT_FOUND, INSUFFICIENT_SCOPE e INVALID_TOKEN. Um id de outra organização sempre dá 404: a API nunca diz se ele existe em outro lugar.