Códigos de error de la API de Zendesk: Guía de referencia completa para 2026

Trabajar con la API de Zendesk significa lidiar con códigos de error. No es una cuestión de si los encontrará, sino de cuándo. Ya sea que esté creando una integración personalizada, automatizando flujos de trabajo de tickets o sincronizando datos entre sistemas, comprender estos códigos de error puede ahorrarle horas de tiempo de depuración.

Esta guía cubre todo lo que necesita saber sobre los códigos de error de la API de Zendesk. Repasaremos los códigos de estado HTTP, los errores de autenticación, la limitación de velocidad e incluso los códigos de estado de entrega de correo electrónico. Al final, tendrá una referencia práctica a la que puede recurrir siempre que algo salga mal.

Si busca reducir la complejidad de la API por completo, herramientas como eesel AI pueden manejar las operaciones de tickets de manera inteligente, minimizando los errores que necesita solucionar en primer lugar. eesel AI actúa como un agente de IA para Zendesk, aprendiendo de sus tickets anteriores y del centro de ayuda para resolver los problemas de los clientes de forma autónoma.

Comprender los códigos de error de la API de Zendesk y los códigos de estado HTTP

La API de Zendesk utiliza códigos de estado HTTP estándar para comunicar el éxito y el fracaso. Estos se dividen en rangos familiares:

• 2xx (Éxito): La solicitud funcionó como se esperaba
• 3xx (Redirección): El recurso se ha movido o no ha cambiado
• 4xx (Error del cliente): Algo está mal con su solicitud
• 5xx (Error del servidor): Algo salió mal del lado de Zendesk

Aquí hay una referencia rápida para los códigos más comunes que encontrará:

Cuando ocurren errores, Zendesk devuelve una respuesta JSON con detalles. Aquí está el formato de error típico:

{
  "error": "RecordInvalid",
  "description": "Record validation errors",
  "details": {
    "value": [
      {
        "type": "blank",
        "description": "can't be blank"
      }
    ]
  }
}

La API de Sell (el CRM de ventas de Zendesk) utiliza un formato ligeramente diferente con una matriz de errors y un objeto meta que contiene el estado HTTP y el ID de solicitud.

Errores de autenticación y autorización: 401 y 403

Los errores 401 y 403 causan la mayor confusión para los desarrolladores nuevos en la API de Zendesk. Ambos se relacionan con el control de acceso, pero fallan en diferentes etapas.

401 No autorizado: Autenticación fallida

Un error 401 significa que Zendesk no pudo autenticar su solicitud. No sabe quién es usted, por lo que no puede verificar los permisos.

Las causas comunes incluyen:

• Falta de encabezados de autorización o están mal formados
• Codificación Base64 incorrecta para la autenticación básica
• Olvidar el sufijo /token al usar tokens de API
• Tokens caducados o revocados
• Usar tokens de OAuth en un encabezado de autenticación básica

Aquí está el formato correcto para la autenticación de token de API:

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

Y en Node.js:

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

Para OAuth, use el esquema Bearer:

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

403 Prohibido: Autenticado pero no autorizado

Un error 403 significa que Zendesk sabe quién es usted, pero no tiene permiso para hacer lo que está intentando hacer.

Las causas comunes incluyen:

• Tokens de OAuth que carecen de los alcances requeridos (un token con tickets:read no puede crear tickets)
• Usar credenciales de usuario final para llamar a puntos finales solo para agentes
• Intentar acceder a recursos que pertenecen a otra marca
• Restricciones de IP habilitadas en la cuenta
• Cuentas de agente suspendidas o degradadas

Si recibe un 403, verifique primero sus alcances de OAuth. Los alcances no se pueden modificar después de la creación del token, por lo que deberá generar un nuevo token con los permisos correctos.

Enfoque de diagnóstico rápido

Al depurar problemas de acceso:

1. Pruebe primero con curl para aislar el problema del código de su aplicación
2. Verifique que esté utilizando el subdominio correcto (los tokens de sandbox y producción no son intercambiables)
3. Confirme que su método de autenticación coincida con su tipo de token
4. Verifique el rol del usuario (muchos puntos finales requieren permisos de agente o administrador)
5. Para OAuth, verifique que su token incluya los alcances requeridos

Limitación de velocidad y regulación: Manejo de errores 429

Zendesk aplica límites de velocidad para garantizar la estabilidad de la API. Cuando exceda estos límites, recibirá un error 429. La respuesta incluye un encabezado Retry-After que indica cuántos segundos esperar antes de volver a intentarlo.

Zendesk también devuelve encabezados de límite de velocidad con cada solicitud:

X-Rate-Limit: 700
X-Rate-Limit-Remaining: 699

Los límites de velocidad varían según el plan: los planes Team obtienen 200 solicitudes por minuto, los planes Professional obtienen 400, los planes Enterprise obtienen 700 y los planes Enterprise Plus obtienen 2500. Los puntos finales masivos y la búsqueda tienen límites más bajos.

Mejores prácticas para manejar los límites de velocidad

Implemente la retirada exponencial en su código:

import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

Para operaciones por lotes:

• Use puntos finales masivos cuando estén disponibles (cuentan como una solicitud pero manejan varios registros)
• Implemente la cola de solicitudes para suavizar el tráfico
• Supervise su encabezado X-Rate-Limit-Remaining y limite de forma proactiva
• Considere usar la paginación basada en cursor en lugar de la basada en desplazamiento para conjuntos de datos grandes

Errores de validación de datos y conflicto: 422 y 409

422 Entidad no procesable

Un error 422 significa que su solicitud es JSON sintácticamente válido, pero semánticamente incorrecto. El servidor no puede procesarlo debido a restricciones de lógica empresarial.

Escenarios comunes:

• Intentar cerrar un ticket que ya está cerrado
• Falta de campos obligatorios (como el asunto o el cuerpo del comentario)
• Valores de campo no válidos (asignar a un agente inexistente)
• Violar las reglas comerciales (establecer una fecha de vencimiento en el pasado)

La respuesta de error generalmente incluye detalles sobre lo que falló específicamente:

{
  "error": "RecordInvalid",
  "description": "Record validation errors",
  "details": {
    "base": [
      {
        "description": "Status: closed is not valid for ticket update"
      }
    ]
  }
}

409 Conflicto

Un error 409 indica un conflicto con el estado actual del recurso. Esto suele suceder cuando dos solicitudes intentan modificar el mismo recurso simultáneamente.

Para evitar errores 409:

• Serialice las solicitudes que modifican el mismo recurso cuando sea posible
• Use el encabezado Idempotency-Key para las solicitudes POST para volver a intentarlo de forma segura sin crear duplicados
• Implemente el bloqueo optimista verificando la marca de tiempo updated_at antes de las actualizaciones

Aquí se explica cómo usar las claves de idempotencia:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "Test", "comment": {"body": "Test"}}}' \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -v -u email/token:token -X POST

Las claves caducan después de dos horas. Reutilizar una clave con diferentes parámetros devuelve un error.

Códigos de estado de entrega de correo electrónico

Cuando trabaje con la API de notificaciones por correo electrónico, encontrará códigos de estado de entrega que van más allá de las respuestas HTTP estándar. Estos indican lo que sucedió después de que Zendesk envió un correo electrónico a sus destinatarios.

La API devuelve información del estado de entrega con propiedades id, name, code y message para cada destinatario. Estos son los códigos más comunes que verá:

Las conexiones de Microsoft Exchange tienen sus propios códigos de error:

Cuando solucione problemas de entrega de correo electrónico, verifique el objeto delivery_status en la respuesta de la API. El campo code contiene el código de estado SMTP, mientras que message proporciona una explicación legible por humanos.

Mejores prácticas de solución de problemas para errores de la API de Zendesk

Cuando encuentre un error, siga este enfoque sistemático:

1. Verifique primero el código de estado. Le indica ampliamente con qué categoría de problema está lidiando.

2. Lea el mensaje de error. Las respuestas de error de Zendesk incluyen mensajes descriptivos. No se limite a verificar el código de estado y adivinar.

3. Pruebe con curl. Antes de depurar el código de su aplicación, verifique que sus credenciales y el formato de la solicitud funcionen con un simple comando curl. Esto aísla los problemas de la API de los errores de la aplicación.

4. Verifique el encabezado X-Zendesk-Request-Id. Cada respuesta incluye este identificador único. Cuando se comunique con el soporte de Zendesk, incluya este ID para que puedan rastrear su solicitud específica en sus registros.

5. Verifique su subdominio. Los tokens de API están limitados a subdominios específicos. Un token para company.zendesk.com no funcionará en company-sandbox.zendesk.com.

6. Revise su método de autenticación. Mezclar Basic Auth, OAuth y JWT es una fuente común de confusión. Asegúrese de que el formato de su encabezado coincida con su tipo de token.

7. Verifique si hay problemas de CORS. La API REST de Zendesk no admite la autenticación de origen del navegador. Las solicitudes de JavaScript del lado del cliente fallarán. Use un servicio de backend o una aplicación de Zendesk con el cliente ZAF en su lugar.

Errores comunes que debe evitar:

• Omitir el sufijo /token en los nombres de usuario de Basic Auth
• Enviar tokens de OAuth con encabezados de Basic Auth en lugar de Bearer
• Usar credenciales de usuario final para puntos finales solo para agentes
• No manejar los errores 429 con la lógica de reintento adecuada
• Ignorar el encabezado Retry-After en las respuestas con límite de velocidad

Maneje los errores de la API de Zendesk automáticamente con eesel AI

Lidiar con los errores de la API es parte de la construcción en cualquier plataforma, pero ¿qué pasaría si pudiera reducir la complejidad por completo? eesel AI funciona como un compañero de equipo de IA para su instancia de Zendesk, manejando las operaciones de tickets de manera inteligente para que realice menos llamadas a la API en primer lugar.

Así es como funciona: en lugar de crear integraciones personalizadas que golpean la API y arriesgan los límites de velocidad, invita a eesel AI a su equipo. Aprende de sus tickets anteriores, artículos del centro de ayuda y macros, luego maneja el soporte de primera línea de forma autónoma. Esto significa menos llamadas a la API, menos errores 429 y menos tiempo dedicado a depurar problemas de autenticación.

Cuando eesel AI necesita interactuar con Zendesk, incluye el manejo de errores incorporado y la lógica de reintento. Los límites de velocidad, las fallas temporales y los errores de conflicto se gestionan automáticamente. Usted define las reglas de escalamiento en inglés sencillo ("Siempre escale las disputas de facturación a un humano") y eesel AI las sigue.

Para los equipos que construyen en Zendesk, este enfoque elimina toda una categoría de errores de API. No necesita implementar la retirada exponencial, administrar los alcances de OAuth o depurar las respuestas 401. eesel AI maneja la complejidad de la integración mientras usted se enfoca en brindar mejores experiencias al cliente.

Si está cansado de solucionar problemas de errores de API y desea ver cómo un compañero de equipo de IA puede simplificar sus operaciones de Zendesk, puede probar eesel AI gratis o reservar una demostración para verlo en acción.