Errores

Todo error de /public/v1 tiene esta forma:

{ "error": { "code": "insufficient_scope", "message": "Falta el permiso catalog.view" } }

details (lista de { path, message }) solo aparece en errores de validación de entrada.

Códigos de /public/v1

HTTP	code	Cuándo
400	invalid_request	El cuerpo o los parámetros no pasan la validación
400	invalid_cursor	?cursor= no es válido o es de otra instalación
400	idempotency_key_required	Falta Idempotency-Key en un POST que crea un documento
400	event_scope_not_allowed	Pediste un evento de webhook sin el permiso que exige
400	unknown_event	El evento de webhook no existe
401	invalid_token	Sin token, token inválido, vencido, revocado o app suspendida (causa nunca distinguida)
403	insufficient_scope	Tu token no tiene el permiso que exige el recurso
404	not_found	El recurso no existe o no es de tu comercio
409	conflict	Por ejemplo, una suscripción que ya existe, o un estado que no admite la operación
409	private_app_not_uninstallable	DELETE /public/v1/installation con la llave de una app privada: no tiene instalación
409	apps_limit_reached	El comercio llegó al tope de apps activas
422	unprocessable_entity	El cuerpo pasa la validación de forma, pero no las reglas de negocio
422	idempotency_key_reused	La clave ya se usó con un cuerpo distinto
429	rate_limited	Pasaste el cupo de lecturas o escrituras por minuto
503	apps_disabled	La plataforma de apps está apagada (global o para ese comercio)

Códigos de OAuth (/oauth/token, /oauth/autorizar)

Sigue el estándar de OAuth 2.0: el code va en el cuerpo de la respuesta de error, no en el sobre { error } de arriba.

error	Cuándo
invalid_client	client_id desconocido o client_secret incorrecto/incompleto
invalid_grant	code vencido (60 s), ya usado, o code_verifier que no coincide con el code_challenge
invalid_scope	Pediste un scope que la app no tiene permitido o que no existe
unsupported_grant_type	grant_type distinto de authorization_code o refresh_token
access_denied	El Dueño rechazó el consentimiento (va en el redirect_uri, no en una respuesta JSON)

Un redirect_uri que no coincide exacto con el registrado nunca redirige: Wink POS muestra el error directamente, porque el redirect no llegó a validarse.