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"}
}
}
| Campo | Lo que contiene |
|---|---|
code | El código de estado, una vez más. |
message | El 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_type | El 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. |
reason | Má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. |
errors | Para 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:
message | Qué ocurre |
|---|---|
FieldRequiredException | Faltan esos elementos, o hay espacios vacíos donde deberían estar. |
FieldValidatorFailedException | Su 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, FieldMaxLengthException | Es demasiado corto o demasiado largo. |
FieldLimitTooLargeException | El valor de limit en la lista supera los 1000 elementos. Es decir, una página puede contener hasta ese número de elementos. |
FieldEmailTypeException, FieldPhoneTypeException | No es una dirección de correo electrónico, ni tampoco un número de teléfono con su código de país. |
FieldNameTypeException | Un nombre que no puede contener todos los caracteres necesarios para formarlo. |
FieldPathSlugTypeException | Un ID o referencia de etiqueta que contiene caracteres distintos de letras, números, guiones y barras. |
FieldDateTypeException | No 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
| Estado | Qué significa | ¿Qué hacer? |
|---|---|---|
| 400 | La 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. |
| 401 | Se 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. |
| 403 | Es 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. |
| 404 | El 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. |
| 500 | InternalError: 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. |
| 503 | TransientException: 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,CaseUserLimitOrTransactionExceptionya 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.