Errores

La API devuelve errores con un JSON estandarizado:

json

{
  "error":   "validation_failed",
  "message": "email no puede estar en blanco",
  "errors":  { "email": ["no puede estar en blanco"] }
}

error es un código estable que debes usar para tomar decisiones en código.
message es texto en español apto para mostrar al usuario final.
errors (opcional, solo en 422 validation_failed) trae los errores por campo.

Códigos por status HTTP

`error`	Cuándo
`invalid_id`	El parámetro `:id` no es un ObjectId válido.

`error`	Cuándo
`invalid_key`	El header Authorization falta, está mal formado, la key no existe, no matchea el digest, o fue revocada. Devolvemos el mismo error en todos esos casos para no filtrar información.

`error`	Cuándo
`origin_not_allowed`	El Origin/Referer no matchea con la lista de dominios permitidos del account.
`insufficient_scope`	La key autenticada no tiene el scope que requiere ese endpoint. El campo `required` te dice cuál falta.

`error`	Cuándo
`not_found`	El recurso con ese `:id` no existe, o existe pero pertenece a otra empresa (deliberadamente devolvemos el mismo error para no filtrar IDs entre tenants).

`error`	Cuándo
`validation_failed`	El payload no pasa las validaciones del modelo. Mira `errors` para el detalle por campo.
`parameter_missing`	El JSON no incluye la llave `data` o un campo obligatorio en `data.<field>`.
`idempotency_key_reused`	El header `Idempotency-Key` ya se usó con un body diferente. Reusar la misma key requiere el MISMO body.
`not_supported_yet`	El endpoint existe pero esta acción no está soportada en Fase 1 (ej. `POST /automations`).

`error`	Cuándo
`idempotency_body_too_large`	Bodies > 100 KB no se pueden idempotency-key. Quita el header o mándalo en partes.

`error`	Cuándo
`https_required`	En producción solo aceptamos HTTPS. Cambia a `https://`.

`error`	Cuándo
`rate_limited`	Excediste el cap de 600 req/min para tu API key. Espera lo que indica el header `Retry-After`.

Lee error, no message: message puede cambiar de redacción; error es contrato estable.
No diferencies 401: nunca te diremos si una key existe pero está mal o si jamás existió. Trata cualquier 401 invalid_key igual: re-emite la key.
Reintenta con backoff exponencial solo en 429 o 5xx. Para 4xx el reintento sin cambios no va a ayudar.
Usa Idempotency-Key en POST para evitar duplicados en reintentos. Ver Idempotencia.