Errores

Los errores comparten un mismo sobre (consulta el resumen). Ramifica según code, registra meta.request_id y trata message como texto en inglés para personas.

Errores del cliente

Código	Estado	Significado y qué hacer
validation_failed	400	Un campo no superó la validación. field lo nombra; details lo explica. Corrige el campo.
bad_request	400	No se pudo leer la petición en absoluto: JSON mal formado, un flujo Content-Encoding roto, un cuerpo interrumpido. No hay campo que corregir; revisa el transporte.
validation_error	400	Se envió X-Account-Id a un endpoint que la prohíbe (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	El cursor de paginación tiene más de 24 horas. Empieza el listado de nuevo.
unauthenticated	401	Token ausente o no válido. Renueva la sesión o revisa la clave.
invalid_signature	401	La firma de un webhook no se pudo verificar. Consulta Webhooks.
forbidden	403	El token es válido, pero no tiene el permiso.
account_context_mismatch	403	X-Account-Id no coincide con la cuenta del token. La idea que tiene el cliente de la empresa actual se ha desviado; vuelve a leerla de la sesión.
not_found	404	El recurso no existe o pertenece a otra cuenta o sitio. La API nunca distingue entre ambos casos.
conflict	409	Conflicto de estado: bloqueo optimista, restricción de unicidad o una acción no permitida en el estado actual (por ejemplo, escribir en una conversación fusionada).
idempotency_key_conflict	409	Se reutilizó la Idempotency-Key con un cuerpo distinto.
payload_too_large	413	El cuerpo supera el límite de esta familia de endpoints.
unsupported_media_type	415	Content-Type incorrecto.
unprocessable	422	JSON válido, pero una regla de negocio lo rechazó (por ejemplo, una franja de reserva fuera del horario de atención).
storage_quota_exceeded	422	La cuenta alcanzó el límite de almacenamiento de su plan. details incluye used_bytes, quota_bytes y requested_bytes; libera espacio o cambia a un plan superior.
rate_limited	429	Reduce el ritmo. Respeta Retry-After y details.retry_after_seconds.

Errores del servidor

Código	Estado	Significado y qué hacer
internal_error	500	Fallo inesperado. Reintenta una vez y después contacta con soporte indicando el request_id.
upstream_unavailable	502	El gateway no pudo llegar al servicio en absoluto. Un reintento breve suele funcionar.
service_unavailable	503	Mantenimiento programado o un disyuntor abierto. Reintenta después del tiempo indicado en la cabecera Retry-After.
ai_vendor_out_of_funds	503	Tu proveedor de IA rechazó la llamada por motivos de facturación (un 402 o un 429 de cuota del proveedor). Recarga la cuenta del proveedor; reintentar no servirá.
upstream_timeout	504	El servicio no respondió a tiempo. Reintenta cuando haya retry_after.

Reintentos

Reintenta 429, 502, 503, 504 y los fallos de red con espera exponencial, y envía la misma Idempotency-Key en el reintento para que una escritura nunca se aplique dos veces. No reintentes otros 4xx que no sean 429.