Contrato de errores del backend

Todas las rutas públicas e internas de Commerce responden con una envoltura estable:

{
  "error": {
    "code": "INVALID_AUTHENTICATION",
    "message": "Invalid credentials",
    "details": null,
    "request_id": "UUID"
  }
}

request_id coincide con el header X-Request-ID. Es generado por Commerce y permite correlacionar una respuesta sin exponer credenciales, payloads o información personal.

Códigos implementados

Código	HTTP	Uso
VALIDATION_ERROR	422	El body, path o query no cumple su schema. details no repite el input sensible.
INVALID_AUTHENTICATION	401	Credenciales o sesión inválidas.
ACCOUNT_CREATION_CONFLICT	409	La cuenta no puede crearse sin confirmar si un email existe.
WEAK_PASSWORD	422	La contraseña incumple la política.
ORGANIZATION_NOT_FOUND	404	Organización ausente o no observable por el caller.
ORGANIZATION_SLUG_CONFLICT	409	Slug de organización ocupado.
INVALID_CONNECTION_INTENT	400	Intent ausente, vencido, consumido o no coincidente.
UNSUPPORTED_INTEGRATION_PROVIDER	422	Provider no habilitado.
RATE_LIMIT_EXCEEDED	429	Ventana de abuso superada.
RATE_LIMITER_UNAVAILABLE	503	Redis no permitió evaluar la protección; se falla cerrado.
REQUEST_TIMEOUT	504	La request superó el límite global de 10 segundos.
HTTP_<status>	variable	Error HTTP generado en el borde.
INTERNAL_ERROR	500	Error no esperado; nunca contiene stacktrace.

Reglas

• Nunca usar el texto del proveedor como mensaje público.
• Nunca incluir passwords, tokens Shopify, cookies, HMAC o bodies crudos en details.
• Toda excepción de dominio se traduce en el borde HTTP.
• Añadir o cambiar códigos exige regenerar OpenAPI cuando altere el contrato y actualizar esta referencia.