Códigos de error
Cada error que devuelve la API de Kivox utiliza una estructura JSON consistente, independientemente del endpoint.
Esta página documenta el formato de los errores y el significado de cada código posible en code. La URL indicada por doc_url apunta directamente a la entrada correspondiente.
La estructura de un error
code, no contra message ni contra el status HTTP
El status HTTP indica la categoría general del error, pero varios códigos distintos pueden compartir el mismo status.
message puede cambiar entre versiones sin que esto se considere un cambio incompatible.
code es el identificador estable previsto para la lógica de su integración.
Estabilidad
Un código sin marca es estable: no cambia ni desaparece entre versiones de la API.
Un código con el prefijo experimental_ representa una categoría de error que Kivox todavía está estabilizando. Su valor serializado o incluso su existencia puede cambiar sin previo aviso.
Si su integración distingue comportamientos según code, incluya siempre un caso de respaldo para cualquier valor desconocido:
Autenticación y permisos
auth_unauthenticated
Status: 401 Unauthorized
La solicitud no incluye credenciales válidas: falta la clave de acceso o la sesión no es válida.
permission_forbidden
Status: 403 Forbidden
Las credenciales son válidas, pero no autorizan la operación solicitada.
Revise los scopes de la clave de acceso en Claves de acceso.
experimental_auth_credentials_invalid experimental
Status: 401 Unauthorized
La credencial proporcionada no corresponde a ninguna clave o sesión reconocida.
experimental_auth_credentials_expired experimental
Status: 401 Unauthorized
La credencial era válida, pero su fecha de expiración ya pasó.
Genere una nueva clave siguiendo el procedimiento de rotación en Claves de acceso.
experimental_auth_credentials_revoked experimental
Status: 401 Unauthorized
La credencial fue revocada explícitamente y ya no puede utilizarse.
experimental_auth_token_consumed experimental
Status: 401 Unauthorized
El token de un solo uso ya fue utilizado en una solicitud anterior.
No puede reutilizarse, incluso si la solicitud anterior falló por otra razón.
Verificación de seguridad
experimental_security_challenge_required experimental
Status: 401 Unauthorized
La operación requiere una verificación de seguridad adicional antes de completarse.
experimental_security_challenge_failed experimental
Status: 403 Forbidden
La verificación de seguridad se intentó, pero no fue válida.
Validación de la solicitud
experimental_validation_field_required experimental
Status: 400 Bad Request
Falta un campo obligatorio en el cuerpo o en los parámetros de la solicitud.
Revise params para identificar el campo específico.
experimental_validation_field_invalid experimental
Status: 400 Bad Request
Un campo está presente, pero su valor no es válido.
También es el código de respaldo para errores de validación que no tienen una categoría más específica. Revise details para obtener el detalle campo por campo.
experimental_request_malformed experimental
Status: 400 Bad Request
La solicitud no pudo interpretarse.
El caso más común es un cuerpo JSON inválido.
Recursos
resource_not_found
Status: 404 Not Found
El recurso solicitado no existe o no es visible para las credenciales actuales.
Kivox no distingue entre ambos casos en la respuesta. Esto evita revelar la existencia de un recurso al que la credencial utilizada no tiene acceso.
resource_already_exists
Status: 409 Conflict
Ya existe un recurso que entra en conflicto con el que intenta crear.
Por ejemplo, puede producirse al intentar crear un workspace con un slug duplicado.
resource_conflict
Status: 409 Conflict
El recurso existe, pero su estado actual no permite la operación solicitada.
experimental_resource_not_found experimental
Status: 404 Not Found
Variante de resource_not_found para un subconjunto de recursos.
experimental_resource_already_exists experimental
Status: 409 Conflict
Variante de resource_already_exists.
experimental_resource_conflict experimental
Status: 409 Conflict
Variante de resource_conflict.
Condición previa
experimental_precondition_failed experimental
Status: 412 Precondition Failed
Una condición necesaria para ejecutar la operación no se cumplió.
Puede ocurrir cuando una operación depende de un estado anterior que cambió entre la lectura realizada por su aplicación y la llegada de la solicitud al servidor.
Límites de uso
experimental_rate_limit_exceeded experimental
Status: 429 Too Many Requests
Se superó el límite de solicitudes permitido durante la ventana de tiempo actual.
Reintente con retroceso exponencial.
experimental_quota_exceeded experimental
Status: 429 Too Many Requests
Se alcanzó un límite de cuota del plan del workspace.
La cuota es independiente del límite de tasa: puede tener margen de solicitudes por segundo y aun así recibir este error si ya consumió la cuota del período actual.
Datos y dependencias
experimental_data_corrupted experimental
Status: 500 Internal Server Error
Kivox detectó datos internamente inconsistentes al procesar la solicitud.
No es un error del cliente y normalmente no hay ningún cambio en la solicitud que pueda evitarlo.
experimental_dependency_upstream_invalid experimental
Status: 502 Bad Gateway
Un servicio del que depende Kivox devolvió una respuesta inválida o no está disponible.
Generalmente es transitorio.
Errores internos
internal_unexpected
Status: 500 Internal Server Error
Un error inesperado del lado de Kivox.
También es el código de respaldo cuando ningún otro código aplica.
Conserve request_id y contacte con soporte si el error persiste después de reintentar.