Central de ajudaIntegrações

Para: Administradores

Lidar com erros e códigos de status da API

Leia o corpo da mensagem de erro, o que significam os códigos 400, 401, 403, 404, 500 e 503 e por que um item que sua chave não consegue ver responde ao erro 404.

Neste artigo5 seções

Esta página explica como ambas as APIs relatam uma chamada rejeitada, tanto para chaves de gerenciamento quanto para chaves de hub.

O corpo do erro

Cada chamada rejeitada responde com um código de status e um corpo em formato JSON.

{
  "error": {
    "code": 400,
    "message": "CaseReferenceIdExistsException",
    "error_type": "ClientException",
    "reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
  }
}
CampoO que contém
codeO código de status, mais uma vez.
messageO nome do erro é, por exemplo, CaseReferenceIdExistsException. Faça com que seu código funcione com esse nome; ele não muda, independentemente da linguagem utilizada pelo leitor.
error_typeO tipo de erro é o seguinte: ClientException para um pedido rejeitado; ApiException para um pedido inválido; SessionException para uma chave ausente; ModelException para uma chave rejeitada ou uma rejeição do armazenamento de dados; TransientException para um problema temporário que justifica a repetição do pedido; InternalError para algum erro no CaseActive.
reasonMais detalhes, se houver algum: as IDs dos registros que entram em conflito, ou o problema no primeiro campo. Geralmente, esses campos estão vazios.
errorsPara uma solicitação inválida, é necessário um único registro por campo.

Erros de campo

Uma solicitação que contenha um campo ausente ou inválido resultará em um código de erro 400 SchemaFieldsException. Para cada campo que não foi informado, será exibida uma entrada com o valor errors. O campo location indica o nome do campo; os pontos são usados para indicar que um campo está dentro de outro. O campo message indica o problema que causou a falha na solicitação.

{
  "error": {
    "code": 400,
    "message": "SchemaFieldsException",
    "error_type": "ApiException",
    "reason": "FieldRequiredException",
    "errors": [
      {"domain": "json", "location": "ref_id", "locationId": "ref_id", "locationType": "schema", "message": "FieldRequiredException", "reason": "FieldRequiredException"}
    ]
  }
}

domain é igual a json no caso do corpo da mensagem, e igual a query nos parâmetros da endereço. Erros comuns nos campos:

messageO que está errado
FieldRequiredExceptionEstá faltando, ou está vazio no lugar onde não deveria estar.
FieldValidatorFailedExceptionSeu valor não é permitido, como um papel, um tipo de caso ou uma fase que seu hub não possui.
FieldMinLengthException, FieldMaxLengthExceptionÉ muito curto ou muito longo.
FieldLimitTooLargeExceptionUma lista de… limit É mais de 1000, ou seja, é o máximo que uma página pode conter.
FieldEmailTypeException, FieldPhoneTypeExceptionNem um endereço de e-mail, nem um número de telefone com seu código de país.
FieldNameTypeExceptionUm nome que não consegue conter todos os caracteres necessários para formar um nome completo.
FieldPathSlugTypeExceptionUma ID de Tag ou ID de Referência que contenha caracteres diferentes de letras, números, traços e barras.
FieldDateTypeExceptionNenhum valor de data, como 2026-03-15

Os campos da API que não são conhecidos pelo sistema são ignorados, e não rejeitados. Portanto, verifique a ortografia dos seus dados em comparação com os dados fornecidos na referência.

Códigos de status

StatusO que significaO que fazer
400A solicitação é inválida, ou a alteração não é permitida. Trata-se de um erro de campo, ou de uma recusa, conforme indicado em message, como por exemplo CaseReferenceIdExistsException.Corrija-o antes de enviá-lo novamente.
401A chave em si foi rejeitada. Veja Autenticação de solicitações da API com uma chave.Pare e verifique a chave.
403A chave pode não funcionar dessa maneira: uma chamada para gerenciar uma chave não pode causar esse problema (BotNotAllowedException). Um hub bloqueado (ManageBillingInactiveException, no caso de uma chave de gerenciamento; BillingReadOnlyException, no caso de uma chave de hub, uma vez que o portal se torna de acesso somente leitura). Um caso fechado (CaseClosedException), ou uma alteração que entrasse em conflito com outra alteração feita no mesmo momento (ItemUpdateFailedException e outras).Identifique a causa do problema. Em caso de conflito, leia o item novamente e tente novamente.
404O item não existe. Provavelmente pertence a outro hub. Ou talvez o item esteja sendo apagado. Além disso, sua chave de acesso não consegue acessar o item.Verifique a identificação.
500InternalError: Um erro no CaseActive. Os desenvolvedores do programa foram informados sobre esse problema.Tente novamente mais tarde. Se o problema persistir, entre em contato com o suporte técnico.
503TransientException: O hub estava muito ocupado por um momento.Tente novamente após um breve período de espera. Espere por mais tempo a cada vez que tentar.

Uma chamada que leva mais de 30 segundos é interrompida pela rede, sem que seja enviado nenhum corpo de dados em formato JSON. As importações evitam isso, pois são executadas em segundo plano.

Por que um item que você sabe que existe responde ao número 404

A chave “hub” funciona como o Assistente VirtualAssistente Virtual Um membro de equipe automatizado que publica mensagens de boas-vindas, atualizações e posts de apresentação para a empresa; suas publicações exibem um selo de Assistente Virtual. do seu hub. Ela só mostra aquilo que o Assistente Virtual pode ver. Um item escondido dessa função gerará uma resposta de 404, assim como um item que não existe. Portanto, a API não revela esse tipo de item. Hoje em dia, editar ou excluir uma fatura publicada, ou editar um arquivo digital publicado, sem que essa função possa ver esses itens, ainda gerará uma resposta de 403 PublishAlreadyPublishedException. As listas excluem esses itens sem dar explicações. Para saber o que essa função permite, leia role::bots com a chave “manage”. Veja também Leia as funções com a chave ‘manage’.

É seguro tentar novamente.

  • 503, e qualquer TransientException, após uma breve espera.
  • 400 TransactionCanceledException, o que acontece em momentos de grande movimentação. Além disso, CaseUserLimitOrTransactionException não está cheio, uma vez que você verificou o caso.
  • 500, um pouco mais tarde.

Não tente novamente com outros códigos de erro como 400, 401, 403 ou 404 – eles serão rejeitados novamente.

Artigos relacionados

Autenticar solicitações de API com uma chaveEnvie sua chave como um token de portador para a API do Painel de Administração para obter uma chave de gerenciamento ou para a API do portal para obter uma chave de hub, e limite-a aos seus endereços IP.IntegraçõesEntenda o que a API pode fazer.Saiba o que uma chave de gerenciamento e uma chave central podem fazer, por que cada chave funciona como um Assistente Virtual e onde encontrar a lista completa de especificações técnicas.Integrações