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"}
}
}
| Campo | O que contém |
|---|---|
code | O código de status, mais uma vez. |
message | O 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_type | O 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. |
reason | Mais detalhes, se houver algum: as IDs dos registros que entram em conflito, ou o problema no primeiro campo. Geralmente, esses campos estão vazios. |
errors | Para 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:
message | O que está errado |
|---|---|
FieldRequiredException | Está faltando, ou está vazio no lugar onde não deveria estar. |
FieldValidatorFailedException | Seu 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. |
FieldLimitTooLargeException | Uma lista de… limit É mais de 1000, ou seja, é o máximo que uma página pode conter. |
FieldEmailTypeException, FieldPhoneTypeException | Nem um endereço de e-mail, nem um número de telefone com seu código de país. |
FieldNameTypeException | Um nome que não consegue conter todos os caracteres necessários para formar um nome completo. |
FieldPathSlugTypeException | Uma ID de Tag ou ID de Referência que contenha caracteres diferentes de letras, números, traços e barras. |
FieldDateTypeException | Nenhum 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
| Status | O que significa | O que fazer |
|---|---|---|
| 400 | A 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. |
| 401 | A chave em si foi rejeitada. Veja Autenticação de solicitações da API com uma chave. | Pare e verifique a chave. |
| 403 | A 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. |
| 404 | O 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. |
| 500 | InternalError: 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. |
| 503 | TransientException: 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,CaseUserLimitOrTransactionExceptionnã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.