Errores

Todo error tiene una forma JSON consistente:

{
  "error": {
    "message": "Explicación legible para humanos, a veces localizada al idioma de la organización.",
    "code": "CODIGO_PARA_MAQUINA"
  }
}

El status HTTP y el error.code siempre son consistentes. Haz switch sobre code, muestra message al usuario final.

Códigos

HTTP	`error.code`	Significado
`400`	`BAD_REQUEST`	Error genérico del cliente.
`400`	`VALIDATION_ERROR`	El cuerpo o query falló validación. El `message` lista los campos problemáticos.
`401`	`UNAUTHORIZED`	Bearer ausente, mal formado, desconocido o expirado.
`403`	`FORBIDDEN`	Autenticado pero sin permiso: scope faltante, límite del plan alcanzado, key inactiva, o regla de negocio violada.
`404`	`NOT_FOUND`	El recurso no existe o pertenece a otra organización.
`429`	`BAD_REQUEST`	Límite de tasa excedido. Reintenta tras `Retry-After` segundos. Ver Límites de tasa.
`500`	`INTERNAL_ERROR`	Falla inesperada del servidor. Es seguro reintentar de forma idempotente tras un breve backoff.

Errores de límite del plan

Los errores FORBIDDEN por límite de plan llevan un mensaje localizado 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). Estos vienen de los billing guards en:

POST /leads — cuando se excede maxLeads.
POST /projects — cuando se excede maxProjects.
POST /webhooks/subscriptions — cuando se excede maxWebhookEndpoints.

Errores de validación

Los mensajes VALIDATION_ERROR listan cada campo que falló en formato path: razón, separados por ; :

{
  "error": {
    "message": "Validation error: email: Invalid email; phone: String must be at most 50 characters",
    "code": "VALIDATION_ERROR"
  }
}

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.
Otras escrituras no son idempotentes. Si reintentas un POST /leads a ciegas, vas a crear duplicados. Usa Buscar un lead primero para deduplicar.

Empezar

Conceptos centrales

Webhooks

Referencia

Códigos

Errores de límite del plan

Errores de validación

Idempotencia y reintentos

​Códigos

​Errores de límite del plan

​Errores de validación

​Idempotencia y reintentos

Códigos

Errores de límite del plan

Errores de validación

Idempotencia y reintentos