Saltar al contenido principal
Todo error tiene una forma JSON consistente:
Cada error.code corresponde a un solo status HTTP, pero un status puede llevar más de un código — 403 es tanto FORBIDDEN como PLAN_LIMIT_REACHED. Haz switch sobre code, no sobre el status, y muestra message al usuario final.

Códigos

Errores de límite del plan

Un límite de plan no es un problema de permisos, pero llega en el mismo status code. Hacé match sobre error.code, no sobre el status:
PLAN_LIMIT_REACHED se agregó para que “tu plan está lleno” deje de ser indistinguible de “a tu key le falta el scope” — antes las dos llegaban como un 403 FORBIDDEN pelado. El status code no cambió, así que los clientes que solo chequean 403 siguen funcionando igual. Los otros dos endpoints siguen devolviendo FORBIDDEN y pasarán a tener código propio en una versión posterior.
Los errores de límite de plan llevan un mensaje que puede venir localizado al idioma de la organización, como “Has alcanzado el número máximo de leads de tu plan.” — muéstraselo al usuario final tal cual, ya que son ellos los que pueden actuar (subir plan o eliminar registros). Reintentar un PLAN_LIMIT_REACHED no sirve de nada hasta que la organización mejore el plan: el veredicto no puede cambiar solo. Alertá en vez de reintentar, y guardá el payload si no podés darte el lujo de perderlo. Una fusión nunca se bloquea por el límite de leads: no se crea ningún lead, así que no consume cupo. Una organización en su tope igual puede seguir enriqueciendo los leads que ya tiene.

Errores de validación

Los mensajes VALIDATION_ERROR listan cada campo que falló en formato path: razón, separados por ; :
Parsea el mensaje si necesitas mostrar errores a nivel de campo en tu propia UI, o muestra el string completo.

Idempotencia y reintentos

  • 5xx y 429 son seguros para reintentar. Usa exponential backoff topado al valor de Retry-After cuando esté presente.
  • 4xx (excepto 429) significa que el request en sí está mal. No reintentes sin cambiarlo.
  • POST /webhooks/subscriptions es idempotente cuando pasas external_id — ver Crear una suscripción.
  • POST /leads es idempotente por identidad de contacto: reintentar con el mismo correo o teléfono fusiona sobre el lead existente en vez de crear un duplicado. Leé outcome en la respuesta para distinguir un alta de una fusión — ver Deduplicación y fusión.
  • Otras escrituras no son idempotentes. Reintentarlas a ciegas crea registros duplicados.