Errores

Las APIs de Admin y Storefront responden los errores con Problem Details y un code estable que identifica el caso:

Respuesta de error

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

Campo	Contenido
`title`	Resumen corto del error.
`detail`	Explicación en inglés para desarrolladores. Su texto puede cambiar.
`status`	Estado HTTP.
`code`	Identificador del caso. Úsalo en tu código para decidir qué hacer.
`traceId`	Identificador de la petición. Inclúyelo cuando escribas a soporte.

Los códigos y su estado están en Códigos de error.

Validación

Un 400 de validación trae code: "Common.Validation", errors con los mensajes en inglés y fieldErrors con un código por campo:

Respuesta de error

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

Un parámetro de la URL o de un encabezado con otro tipo, como limit=abc, responde igual, con el nombre del parámetro como clave.

Las claves de fieldErrors son rutas en camelCase con índices, como items[0].sku. La clave vacía ("") es un error del formulario completo. Traduce cada código para mostrar el motivo junto a su campo:

Código	Motivo
`Fields.Required`	Falta el valor.
`Fields.Length`	El texto es muy corto o muy largo.
`Fields.Range`	El número está fuera del rango aceptado.
`Fields.Email`	El correo no es válido.
`Fields.Format`	El valor no tiene el formato esperado.
`Fields.Option`	El valor no es una de las opciones.
`Fields.Invalid`	El valor no es válido.

Un campo también puede traer un código de dominio, como Search.InvalidFacetFilter.

Operaciones en segundo plano

Las importaciones, exportaciones y otros trabajos largos se consultan en GET /v1/operations/{id}. Si una falla, errorCode trae el código para mostrar al usuario y error el diagnóstico en inglés.

Errores OAuth

POST /connect/token responde los errores con el formato de OAuth 2.0:

Respuesta de error

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

Decide con error. Los valores habituales están en Autorización de usuarios.

Qué hacer según el estado

Estado	Significado	Qué hacer
`400`	Cuerpo, parámetro o transición inválida.	Corrige la petición.
`401`	Falta el token o venció.	Pide un token nuevo y repite.
`403`	El token no tiene el permiso, la tienda o el vendedor.	Revisa los permisos de la aplicación y el contexto.
`404`	El recurso no existe en la tienda o el vendedor del token.	Revisa el identificador y el contexto.
`409`	El estado actual del recurso impide la operación.	Lee el recurso y decide con su estado nuevo.
`429`	Superaste un límite de uso.	Espera los segundos de `Retry-After` y repite.
`500`	Error interno.	Repite con espera creciente si la operación es segura de repetir.
`503`	El servicio está ocupado o no disponible.	Espera unos segundos, o los de `Retry-After`, y repite.

Reintentos

Un 429, o un 503 con code: "Storefront.Busy", se rechazó antes de ejecutarse: repítelo. Ante un 500 o un corte de red, repite solo lo que no se duplica:

Lecturas (GET).
Escrituras con idempotencyKey en el cuerpo, como pagos, reembolsos, devoluciones y cancelaciones con reembolso de pedidos. Repite con la misma clave y la operación se aplica una sola vez.

Para otras escrituras, lee el recurso antes de repetir y confirma si el primer intento se aplicó.

Errores

Validación

Operaciones en segundo plano

Errores OAuth

Qué hacer según el estado

Reintentos

En esta página