El error 403 SCOPE_MISMATCH para la Búsqueda de Tickets significa que el token de acceso que enviaste no incluye el alcance (scope) de la API de Desk requerido para llamar al endpoint de Búsqueda de Tickets; Zoho rechaza la solicitud por motivos de autorización. Esto suele ocurrir después de un cambio de alcance, una actualización de token que perdió alcances, o cuando una aplicación nunca obtuvo los alcances de búsqueda/tickets de Desk [3][4].
Qué significa
La capa de autorización de Zoho compara los alcances OAuth adjuntos al token de portador con el endpoint de la API que llamas. El endpoint de Búsqueda de Tickets requiere alcances específicos de búsqueda/tickets de Desk; si el token carece de esos alcances, la API devuelve 403 SCOPE_MISMATCH en lugar de un error de datos o sintaxis [3]. El error es una falla de autorización ligada a las declaraciones de alcance OAuth, no a la sintaxis COQL o de consulta.
Causas comunes
- Tu cliente/token OAuth se creó o actualizó sin solicitar o aprobar los alcances de búsqueda/tickets de Desk [3].
- El usuario o administrador revocó el permiso de la aplicación o eliminó los alcances requeridos después del consentimiento inicial [3][4].
- Actualizaste/obtuviste un token de acceso usando un flujo de concesión diferente (o un cliente diferente) que no solicita los mismos alcances [4].
- Usando un token en caché de larga duración emitido antes de que agregaras el alcance de búsqueda/tickets al cliente; el token antiguo nunca tuvo el nuevo alcance [3].
Cómo solucionarlo
- Confirma los alcances requeridos: verifica qué alcances de Desk requiere el endpoint de Búsqueda de Tickets en la documentación de la API de Zoho Desk o en las notas de tu integración, luego enumera los alcances que tu aplicación debe solicitar.
- Actualiza la solicitud OAuth: agrega los alcances de búsqueda/tickets de Desk requeridos a tu URL de autorización o al parámetro de alcance en la solicitud de token.
- Vuelve a consentir como usuario/administrador: abre la URL de autorización para que el usuario (o el administrador de la organización si se requiere consentimiento del administrador) vuelva a otorgar el conjunto de alcances actualizado. Para acceso a nivel de organización, inicia sesión como administrador a través de Zoho Accounts > Aplicaciones autorizadas.
- Genera un token de acceso nuevo: después del consentimiento, intercambia el código de autorización (o usa el flujo de actualización que solicita alcances) para obtener un nuevo token de acceso y verifica sus alcances. No reutilices el token antiguo.
- Prueba la llamada: reintenta la solicitud de Búsqueda de Tickets con el nuevo token y confirma que el error 403 desaparece. Registra la declaración de alcance del token para futuras depuraciones.
Cuándo escalar
Si al volver a solicitar los alcances y obtener un nuevo token no se resuelve el error 403, abre un ticket de soporte con Zoho Desk. Incluye tu ID de cliente, la lista exacta de alcances que solicitaste, la hora de la solicitud fallida, y el endpoint completo de la API y las cabeceras (redacta los secretos); el soporte de Zoho puede verificar el consentimiento a nivel de organización y las asignaciones de alcance [3][4].