Centro de ayudaIntegraciones

Para: Administradores

Gestionar errores de API y códigos de estado

Lea el cuerpo del error, qué significan los códigos 400, 401, 403, 404, 500 y 503, y por qué un elemento que su clave no puede ver responde con el código 404.

En este artículo5 secciones

Esta página explica cómo ambas API’s reportan una llamada rechazada, tanto para las claves de gestión como para las claves del centro de control.

El cuerpo del error

Cada llamada rechazada responde con un código de estado y un cuerpo en formato JSON.

{
  "error": {
    "code": 400,
    "message": "CaseReferenceIdExistsException",
    "error_type": "ClientException",
    "reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
  }
}
CampoLo que contiene
codeEl código de estado, una vez más.
messageEl nombre del error es, por ejemplo, CaseReferenceIdExistsException. Haga que su código funcione con este valor; este valor no cambia, independientemente del idioma utilizado por el lector.
error_typeEl tipo de error: ClientException cuando se produce una negativa; ApiException cuando se trata de una solicitud inválida; SessionException cuando falta algún dato importante; ModelException cuando el dato solicitado no está disponible o cuando se produce una negativa por parte del almacén de datos; TransientException cuando hay problemas temporales que justifican la necesidad de volver a intentar la solicitud; InternalError cuando se produce algún error en CaseActive.
reasonMás detalles, si es posible: las identificaciones de los registros que coinciden entre sí, o el problema en el primer campo. A menudo, estos campos están vacíos.
errorsPara una solicitud inválida, se permite solo un registro por campo.

Errores de campo

Un pedido que contenga campos faltantes o inválidos genera una respuesta de tipo 400 SchemaFieldsException. En este caso, se utiliza un campo errors para indicar cada uno de los campos. El nombre del campo se escribe como location; los puntos se utilizan para indicar que hay un campo dentro de otro. Finalmente, el campo message indica el problema que se presenta en el pedido.

{
  "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 es json para el cuerpo del mensaje, y query para los parámetros de la dirección. Errores comunes en los campos:

messageQué ocurre
FieldRequiredExceptionFaltan esos elementos, o hay espacios vacíos donde deberían estar.
FieldValidatorFailedExceptionSu valor no es válido. Por ejemplo, no puede ser un rol, un tipo de caso o una etapa que su centro no tenga.
FieldMinLengthException, FieldMaxLengthExceptionEs demasiado corto o demasiado largo.
FieldLimitTooLargeExceptionEl valor de limit en la lista supera los 1000 elementos. Es decir, una página puede contener hasta ese número de elementos.
FieldEmailTypeException, FieldPhoneTypeExceptionNo es una dirección de correo electrónico, ni tampoco un número de teléfono con su código de país.
FieldNameTypeExceptionUn nombre que no puede contener todos los caracteres necesarios para formarlo.
FieldPathSlugTypeExceptionUn ID o referencia de etiqueta que contiene caracteres distintos de letras, números, guiones y barras.
FieldDateTypeExceptionNo se trata de una fecha, como por ejemplo 2026-03-15

Los campos que la API no conoce se ignoran, no se rechazan. Por lo tanto, verifique su ortografía con respecto a los datos de referencia.

Códigos de estado

EstadoQué significa¿Qué hacer?
400La solicitud es inválida, o la modificación no está permitida. Se trata de un error en los campos, o de una negativa, como se indica en message. Ejemplos de tales situaciones son CaseReferenceIdExistsException.Corrígelo antes de enviarlo nuevamente.
401Se rechazó la entrega de la clave necesaria para autenticar las solicitudes de la API. Para más información, vea Autenticar solicitudes de la API con una clave.Deténte y revisa la llave.
403Es posible que la llave no funcione en estos casos: una llamada para gestionar una llave no puede hacer nada (BotNotAllowedException); un concentrador bloqueado (ManageBillingInactiveException, en el caso de una llave de gestión; BillingReadOnlyException, en el caso de una llave de concentrador, una vez que el portal se convierte en de solo lectura); un caso cerrado (CaseClosedException); o un cambio que entrare en conflicto con otro cambio realizado al mismo tiempo (ItemUpdateFailedException y otros).Identifica la causa del problema. En caso de que haya un conflicto, lee el contenido una vez más y luego intenta nuevamente.
404El artículo no existe. Puede que pertenezca a otro centro de almacenamiento, o que esté siendo eliminado. También es posible que su clave no pueda acceder al artículo.Verifique la identificación.
500InternalError: Un error en CaseActive. A los desarrolladores de esta aplicación se les ha informado al respecto.Intente de nuevo más tarde. Si el problema persiste, contácte al soporte técnico.
503TransientException: El centro de control estaba demasiado ocupado en ese momento.Intente nuevamente después de una breve espera. La espera se prolonga cada vez que se intenta de nuevo.

Un llamado que dura más de 30 segundos se corta debido a un error del servicio de red, sin que haya un cuerpo de datos en formato JSON. Los importes evitan este problema al ejecutarse en segundo plano.

¿Por qué existe un elemento que usted sabe? Respuestas 404

La clave “hub” funciona como el Asistente VirtualAsistente virtual Un miembro del equipo automatizado que publica mensajes de bienvenida, registros de asistencia y actualizaciones de la empresa; sus publicaciones llevan una insignia de Asistente Virtual. de tu hub. Solo muestra lo que la función del Asistente Virtual puede ver. Un elemento oculto para esa función genera una respuesta 404; esto es lo mismo que cuando un elemento no existe, por lo que la API no lo revela. Hoy en día, editar o eliminar una factura publicada, o editar un archivo electrónico publicado, aquellos elementos que esa función no puede ver, todavía generan una respuesta 403 PublishAlreadyPublishedException. Las listas excluyen tales elementos sin indicarlo explícitamente. Para saber qué es lo que esa función permite, lee role::bots utilizando la clave “manage”. Consulte también Leer información sobre las funciones con la clave “manage”.

Es seguro volver a intentarlo.

  • 503, y cualquier valor de tipo TransientException, después de una breve espera.
  • 400 TransactionCanceledException, lo cual ocurre en momentos de gran actividad. Además, CaseUserLimitOrTransactionException ya no está lleno después de haber verificado el caso.
  • 500, un poco más tarde.

No intente nuevamente con otros códigos de error del tipo 400, 401, 403 o 404. Estos códigos se rechazarán una vez más.

Artículos relacionados

Autenticar las solicitudes de API con una clave.Envía tu clave como token de portador a la API del panel de administración para obtener una clave de gestión o a la API del portal para obtener una clave central, y limita su uso a tus direcciones IP.IntegracionesEntienda lo que la API puede hacerDescubre qué funciones pueden alcanzar una clave de administración y una clave de concentrador, por qué cada clave actúa como asistente virtual y dónde encontrar la lista técnica completa.Integraciones