Códigos de erro da API Zendesk: Guia de referência completo para 2026

Trabalhar com a API Zendesk significa lidar com códigos de erro. Não é uma questão de se você os encontrará, mas quando. Se você estiver construindo uma integração personalizada, automatizando fluxos de trabalho de tickets ou sincronizando dados entre sistemas, entender esses códigos de erro pode economizar horas de tempo de depuração.

Este guia cobre tudo o que você precisa saber sobre os códigos de erro da API Zendesk. Vamos percorrer os códigos de status HTTP, erros de autenticação, limitação de taxa e até mesmo códigos de status de entrega de e-mail. Ao final, você terá uma referência prática para consultar sempre que algo der errado.

Se você está procurando reduzir a complexidade da API, ferramentas como eesel AI podem lidar com as operações de tickets de forma inteligente, minimizando os erros que você precisa solucionar em primeiro lugar. O eesel AI atua como um agente de IA para Zendesk, aprendendo com seus tickets anteriores e central de ajuda para resolver problemas de clientes de forma autônoma.

Entendendo os códigos de erro da API Zendesk e os códigos de status HTTP

A API Zendesk usa códigos de status HTTP padrão para comunicar sucesso e falha. Estes se enquadram em faixas familiares:

• 2xx (Sucesso): A solicitação funcionou como esperado
• 3xx (Redirecionamento): O recurso foi movido ou não foi alterado
• 4xx (Erro do Cliente): Algo está errado com sua solicitação
• 5xx (Erro do Servidor): Algo deu errado no lado do Zendesk

Aqui está uma referência rápida para os códigos mais comuns que você encontrará:

Quando ocorrem erros, o Zendesk retorna uma resposta JSON com detalhes. Aqui está o formato de erro típico:

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

A API Sell (CRM de vendas do Zendesk) usa um formato ligeiramente diferente com um array errors e um objeto meta contendo o status HTTP e o ID da solicitação.

Erros de autenticação e autorização: 401 e 403

Os erros 401 e 403 causam a maior confusão para desenvolvedores novos na API Zendesk. Ambos se relacionam ao controle de acesso, mas falham em estágios diferentes.

401 Não Autorizado: Autenticação falhou

Um erro 401 significa que o Zendesk não pôde autenticar sua solicitação. Ele não sabe quem você é, então não pode verificar as permissões.

Causas comuns incluem:

• Cabeçalhos de Autorização ausentes ou malformados
• Codificação Base64 incorreta para Autenticação Básica
• Esquecer o sufixo /token ao usar tokens de API
• Tokens expirados ou revogados
• Usar tokens OAuth em um cabeçalho de Autenticação Básica

Aqui está o formato correto para autenticação de token de API:

curl -v \
  -u "agent@example.com/token:SEU_TOKEN_DE_API" \
  "https://seu_subdomínio.zendesk.com/api/v2/tickets.json"

E em Node.js:

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

const subdomain = "seu_subdomínio";
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 o esquema Bearer:

curl \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
  "https://seu_subdomínio.zendesk.com/api/v2/users/me.json"

403 Proibido: Autenticado, mas não autorizado

Um erro 403 significa que o Zendesk sabe quem você é, mas você não tem permissão para fazer o que está tentando fazer.

Causas comuns incluem:

• Tokens OAuth faltando escopos obrigatórios (um token com tickets:read não pode criar tickets)
• Usar credenciais de usuário final para chamar endpoints somente para agentes
• Tentativa de acessar recursos pertencentes a outra marca
• Restrições de IP habilitadas na conta
• Contas de agente suspensas ou rebaixadas

Se você receber um 403, verifique seus escopos OAuth primeiro. Os escopos não podem ser modificados após a criação do token, então você precisará gerar um novo token com as permissões corretas.

Abordagem de diagnóstico rápido

Ao depurar problemas de acesso:

1. Teste com curl primeiro para isolar o problema do código do seu aplicativo
2. Verifique se você está usando o subdomínio correto (tokens de sandbox e produção não são intercambiáveis)
3. Confirme se seu método de autenticação corresponde ao seu tipo de token
4. Verifique a função do usuário (muitos endpoints exigem permissões de agente ou administrador)
5. Para OAuth, verifique se seu token inclui os escopos necessários

Limitação de taxa e throttling: Lidando com erros 429

O Zendesk impõe limites de taxa para garantir a estabilidade da API. Quando você excede esses limites, você receberá um erro 429. A resposta inclui um cabeçalho Retry-After indicando quantos segundos esperar antes de tentar novamente.

O Zendesk também retorna cabeçalhos de limite de taxa com cada solicitação:

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

Os limites de taxa variam de acordo com o plano: os planos Team recebem 200 solicitações por minuto, os planos Professional recebem 400, os planos Enterprise recebem 700 e os planos Enterprise Plus recebem 2.500. Endpoints em massa e pesquisa têm limites mais baixos.

Melhores práticas para lidar com limites de taxa

Implemente o backoff exponencial em seu 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 operações em lote:

• Use endpoints em massa quando disponíveis (eles contam como uma solicitação, mas lidam com vários registros)
• Implemente o enfileiramento de solicitações para suavizar o tráfego
• Monitore seu cabeçalho X-Rate-Limit-Remaining e limite proativamente
• Considere usar a paginação baseada em cursor em vez de baseada em deslocamento para grandes conjuntos de dados

Validação de dados e erros de conflito: 422 e 409

422 Entidade Não Processável

Um erro 422 significa que sua solicitação é JSON sintaticamente válido, mas semanticamente incorreta. O servidor não pode processá-lo devido a restrições de lógica de negócios.

Cenários comuns:

• Tentando fechar um ticket que já está fechado
• Campos obrigatórios ausentes (como assunto ou corpo do comentário)
• Valores de campo inválidos (atribuindo a um agente inexistente)
• Violação de regras de negócios (definir uma data de vencimento no passado)

A resposta de erro geralmente inclui detalhes sobre o que falhou especificamente:

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

409 Conflito

Um erro 409 indica um conflito com o estado atual do recurso. Isso normalmente acontece quando duas solicitações tentam modificar o mesmo recurso simultaneamente.

Para evitar erros 409:

• Serializar solicitações que modificam o mesmo recurso quando possível
• Use o cabeçalho Idempotency-Key para solicitações POST para tentar novamente com segurança sem criar duplicatas
• Implemente o bloqueio otimista verificando o timestamp updated_at antes das atualizações

Veja como usar chaves de idempotência:

curl https://{subdomínio}.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

As chaves expiram após duas horas. Reutilizar uma chave com parâmetros diferentes retorna um erro.

Códigos de status de entrega de e-mail

Ao trabalhar com a API de Notificações por E-mail, você encontrará códigos de status de entrega que vão além das respostas HTTP padrão. Estes indicam o que aconteceu depois que o Zendesk enviou um e-mail para seus destinatários.

A API retorna informações de status de entrega com propriedades id, name, code e message para cada destinatário. Aqui estão os códigos mais comuns que você verá:

As conexões do Microsoft Exchange têm seus próprios códigos de erro:

Ao solucionar problemas de entrega de e-mail, verifique o objeto delivery_status na resposta da API. O campo code contém o código de status SMTP, enquanto message fornece uma explicação legível.

Melhores práticas de solução de problemas para erros da API Zendesk

Quando você encontrar um erro, siga esta abordagem sistemática:

1. Verifique o código de status primeiro. Ele informa amplamente com qual categoria de problema você está lidando.

2. Leia a mensagem de erro. As respostas de erro do Zendesk incluem mensagens descritivas. Não apenas verifique o código de status e adivinhe.

3. Teste com curl. Antes de depurar o código do seu aplicativo, verifique se suas credenciais e formato de solicitação funcionam com um comando curl simples. Isso isola problemas de API de bugs de aplicativos.

4. Verifique o cabeçalho X-Zendesk-Request-Id. Cada resposta inclui este identificador exclusivo. Ao entrar em contato com o suporte do Zendesk, inclua este ID para que eles possam rastrear sua solicitação específica em seus logs.

5. Verifique seu subdomínio. Os tokens de API são definidos para subdomínios específicos. Um token para company.zendesk.com não funcionará em company-sandbox.zendesk.com.

6. Revise seu método de autenticação. Misturar Basic Auth, OAuth e JWT é uma fonte comum de confusão. Certifique-se de que o formato do seu cabeçalho corresponda ao seu tipo de token.

7. Verifique se há problemas de CORS. A API REST do Zendesk não oferece suporte à autenticação de origem do navegador. As solicitações JavaScript do lado do cliente falharão. Use um serviço de back-end ou um aplicativo Zendesk com o cliente ZAF.

Erros comuns a serem evitados:

• Omitir o sufixo /token em nomes de usuário Basic Auth
• Enviar tokens OAuth com cabeçalhos Basic Auth em vez de Bearer
• Usar credenciais de usuário final para endpoints somente para agentes
• Não lidar com erros 429 com a lógica de repetição adequada
• Ignorar o cabeçalho Retry-After em respostas com limite de taxa

Lide com erros da API Zendesk automaticamente com o eesel AI

Lidar com erros de API faz parte da construção em qualquer plataforma, mas e se você pudesse reduzir a complexidade completamente? eesel AI funciona como um colega de equipe de IA para sua instância do Zendesk, lidando com as operações de tickets de forma inteligente para que você faça menos chamadas de API em primeiro lugar.

Veja como funciona: em vez de construir integrações personalizadas que sobrecarregam a API e arriscam limites de taxa, você convida o eesel AI para sua equipe. Ele aprende com seus tickets anteriores, artigos da central de ajuda e macros, e então lida com o suporte de linha de frente de forma autônoma. Isso significa menos chamadas de API, menos erros 429 e menos tempo gasto na depuração de problemas de autenticação.

Quando o eesel AI precisa interagir com o Zendesk, ele inclui tratamento de erros e lógica de repetição integrados. Limites de taxa, falhas temporárias e erros de conflito são gerenciados automaticamente. Você define regras de escalonamento em português claro ("Sempre encaminhe disputas de cobrança para um humano") e o eesel AI as segue.

Para equipes que constroem no Zendesk, essa abordagem elimina toda uma categoria de erros de API. Você não precisa implementar backoff exponencial, gerenciar escopos OAuth ou depurar respostas 401. O eesel AI lida com a complexidade da integração enquanto você se concentra em oferecer melhores experiências ao cliente.

Se você está cansado de solucionar problemas de erros de API e quer ver como um colega de equipe de IA pode simplificar suas operações do Zendesk, você pode experimentar o eesel AI gratuitamente ou agendar uma demonstração para vê-lo em ação.