Errores

Los errores usan JSON y contienen al menos error; muchas respuestas también incluyen message y, en conflictos específicos, codigo.

{
  "error": "Forbidden",
  "message": "Tu token o plan no tiene acceso a este endpoint."
}

Códigos documentados

Estado	Casos confirmados
400	Parámetros, identificadores o bodies inválidos.
401	Token ausente, inválido, revocado o sin acceso vigente.
402	La tienda alcanzó su límite de productos al crear un producto.
403	El plan o los scopes no permiten la operación.
404	Recurso no encontrado dentro de la tienda del token.
409	Duplicados, conflictos de stock, jerarquía, relaciones o idempotencia.
422	Reglas de negocio o límites específicos no satisfechos.
429	Límite por credencial, tienda o ráfaga superado.
500	Fallo interno al crear o actualizar ciertos recursos.

No todas las operaciones declaran todos los estados. Consultá las respuestas de la operación concreta en la referencia API.

Un 401 al usar la API indica que la credencial es inválida, está ausente o fue revocada; revisá emisión, uso y revocación de API keys. Para receptores de eventos, las respuestas que no sean 2xx, los errores de red y los timeouts activan la política documentada de reintentos de webhooks.

Recomendación de manejo

Conservá el estado HTTP y el campo codigo cuando exista para decidir si el error es corregible, reintentable o requiere intervención. El contrato no define un catálogo global cerrado de valores para codigo; documentarlos de manera exhaustiva queda pendiente.