Errores

El formato depende de quién rechaza la petición. Los errores producidos por el flujo de aplicación usan Problem Details y un code; Auth, un limitador o un gateway pueden responder con otra estructura.

Errores de aplicación

Un error de dominio o aplicación usa Problem Details:

{
  "title": "Not Found",
  "detail": "Product 7204558912004325377 does not exist.",
  "status": 404,
  "code": "Catalog.ProductNotFound"
}

Campo	Uso
`title`	Categoría legible del error.
`detail`	Explicación para diagnóstico; puede cambiar.
`status`	Estado HTTP asociado.
`code`	Identificador de aplicación para manejar el caso cuando está presente.

Usa code para distinguir casos conocidos y conserva status como respaldo. No tomes decisiones con el texto de detail.

Validación

Los errores de validación pueden agregar errors con uno o más mensajes por campo:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "code": "Common.Validation",
  "errors": {
    "limit": ["The limit must be between 1 and 200."]
  }
}

Muestra esos mensajes para corregir la entrada. No asumas que todos los endpoints aceptan el mismo rango o usan la misma clave.

Errores OAuth

POST /connect/token sigue el formato OAuth. Un fallo puede verse así:

{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid."
}

Maneja error y el estado HTTP. No esperes title, status o code en esta respuesta.

Errores de infraestructura

Un gateway, un limitador de tasa o un limitador de concurrencia puede responder antes de llegar a la aplicación. Conserva el estado, los encabezados y un identificador de petición si existe.

No intentes deserializar todas las respuestas de error en un único modelo obligatorio. Valida el Content-Type y admite un cuerpo vacío o distinto.

Qué hacer según el estado

Estado	Interpretación habitual	Acción inicial
`400`	Cuerpo, parámetro o transición inválida.	Corrige la petición; no la repitas sin cambios.
`401`	Falta una credencial válida.	Obtén otra credencial y reintenta una vez si la operación es segura.
`403`	Una política, scope, permiso o contexto bloqueó la operación.	Revisa autorización y contexto.
`404`	El recurso no existe en el contexto visible.	Verifica identificador, tienda y vendedor.
`409`	El estado actual entra en conflicto con la operación.	Lee el recurso y decide con el estado nuevo.
`429`	Se alcanzó un límite de tasa o concurrencia.	Respeta `Retry-After` si existe y aplica espera.
`5xx`	Fallo temporal o interno.	Reintenta solo cuando repetir la operación sea seguro.

El significado específico de un code y las respuestas declaradas están en la referencia del endpoint.

Reintentos

Un estado reintentable no vuelve reintentable a la operación. Antes de repetir, confirma que el método sea idempotente, que exista una clave de idempotencia o que puedas comprobar si el primer intento terminó.

function mayRetry(response: Response, canReplay: boolean) {
  if (!canReplay) return false;
  return response.status === 429 || response.status >= 500;
}

Usa espera exponencial con variación aleatoria y un máximo de intentos. En un POST, evita el reintento automático salvo que el contrato documente idempotencia.