invalid_request | 400 | El request está mal armado: JSON inválido, un campo o parámetro que no existe, un valor fuera de rango (por ejemplo limit), un cursor inválido o de otros filtros, un body de más de 1 MiB, o falta el Idempotency-Key donde es obligatorio. | Corregí el request. details trae { field, message } por cada problema. No reintentes igual. |
invalid_token | 401 | Falta el header Authorization: Bearer, el access token es inválido o venció, la instalación ya no está activa (desinstalada o revocada), o la app no está disponible para esa tienda. | Renová el access token con el refresh token. Si el refresh también falla, la tienda tiene que volver a autorizar la app. |
insufficient_scope | 403 | La instalación no tiene el scope que pide el endpoint. details trae { "required_scope": "..." }. | Pedí el scope en el portal y pedile al comerciante que vuelva a autorizar (ver Scopes y permisos). |
plan_required | 403 | El plan actual del comercio no incluye apps, o llegó a un tope de su plan (por ejemplo la cantidad de productos). | Si el comercio bajó de plan, la instalación sigue, pero la API y los webhooks no obligatorios quedan pausados hasta que vuelva a un plan que incluya apps. Avisale al comerciante. |
account_suspended | 403 | La cuenta del comercio está suspendida o con el medio de pago pendiente. | No reintentes. La operatoria vuelve cuando el comercio regulariza su cuenta. |
not_found | 404 | El recurso no existe, o pertenece a otro comercio (nunca confirmamos que existe), o la ruta o la versión de la API no existe. | Revisá el id y la URL. Un id de otro comercio es indistinguible de uno inexistente. |
conflict | 409 | El request choca con el estado actual: un request con el mismo Idempotency-Key todavía en curso, o una regla de negocio (por ejemplo una entrega que exige confirmar el cobro). details[0].reason indica el motivo. | Leé details, resolvé el conflicto y reintentá. Si es un Idempotency-Key en curso, esperá unos segundos y reenviá lo mismo. |
idempotency_conflict | 422 | Reusaste un Idempotency-Key con un body distinto al del primer request. | Generá una clave nueva para cada operación distinta. |
rate_limited | 429 | Superaste el límite de requests de tu app para esa tienda. | Esperá lo que indica el header Retry-After y reintentá con backoff (ver Límites de uso). |
internal_error | 500 | Falló algo de nuestro lado. | Reintentá con backoff exponencial. Si persiste, escribinos con el request_id. |
