Límites de uso (rate limits) y errores
La API responde errores estándar HTTP con un JSON { error, message }, y aplica límites de tasa para proteger el servicio: al superarlos recibes 429 y tienes que reintentar con backoff.
Códigos de error
| Código | Qué significa | Qué hacer |
|---|---|---|
400 | Petición inválida (falta un campo, formato erróneo) | Revisa el body contra la doc del endpoint |
401 | Token ausente o inválido | Verifica el header Authorization (autenticación) |
403 | Token válido pero sin permiso (o límite de plan) | Revisa rol y plan |
404 | El recurso no existe en tu workspace | Verifica el id — los ids son por workspace |
429 | Rate limit superado | Espera y reintenta con backoff exponencial |
5xx | Error del lado de MelonHelp | Reintenta con backoff; si persiste, repórtalo |
Manejo de reintentos
- Reintenta solo
429y5xx— nunca4xx(el error es del request). - Backoff exponencial con jitter: 1s, 2s, 4s…
- Haz tus handlers idempotentes: un reintento no debe duplicar efectos.
Límites de plan vs rate limits
No confundas: el rate limit protege el servicio (picos por minuto); los límites de plan definen tu capacidad mensual (agentes, conversaciones). El 403 con mensaje de plan es del segundo tipo.