Conceptos
Errores
Kuida responde con los códigos HTTP estándar y un cuerpo de error con el mismo formato en todas las operaciones.
Formato
Toda respuesta que no es 2xx trae un objeto error. type dice de qué clase es el problema y code qué pasó exactamente; los dos son estables y se puede programar contra ellos. message es para personas y su redacción puede cambiar.
{
"error": {
"type": "invalid_request_error",
"code": "parameter_missing",
"message": "Falta el parámetro obligatorio: phone",
"param": "phone",
"requestId": "req_Nw3xQ2c9b8f7a6e5d4c3b2a1",
"docUrl": "https://www.kuida.ar/desarrolladores/errores#parameter_missing"
}
}typeenumCategoría del error. Los SDKs la mapean a una clase de excepción.
Valores:
invalid_request_errorauthentication_errorpermission_erroridempotency_errorrate_limit_errorapi_errorcodeenumQué pasó, en forma estable para programar contra ella.
Valores:
parameter_missingparameter_invalidbody_invalid_jsonbody_too_largebatch_too_largeresource_missingresource_conflictapi_key_missingapi_key_invalidapi_key_revokedapi_key_expiredscope_missingservice_not_contractedapi_version_invalididempotency_key_in_useidempotency_key_reusedrate_limitedprocessing_failedinternal_errormessagestringExplicación para una persona. Puede cambiar de redacción.
paramstringpuede ser nullEl parámetro que causó el error, si aplica (
patient.phone).requestIdstringId del pedido. Envíelo si escribe a soporte.
docUrlstringLink a la explicación del código de error.
Toda respuesta, con error o sin él, trae el header Request-Id. Si escribe a soporte, inclúyalo: identifica el pedido exacto.
Tipos de error y excepciones de los SDKs
invalid_request_error- HTTP400, 404, 409, 413
- CuándoEl pedido tiene un problema: falta un parámetro, un valor no es válido, el objeto no existe o hay un conflicto.
authentication_error- HTTP401
- CuándoLa clave falta, está mal formada, no existe, fue revocada o venció.
permission_error- HTTP403
- CuándoLa clave es válida pero no tiene el permiso, o la organización no tiene la línea de servicio.
idempotency_error- HTTP400, 409
- CuándoLa Idempotency-Key ya se usó con otro pedido o hay un pedido en curso con la misma clave.
rate_limit_error- HTTP429
- CuándoSe superó el límite de 600 pedidos por minuto de la clave.
api_error- HTTP500
- CuándoError de Kuida. El pedido se puede reintentar con la misma Idempotency-Key.
Los SDKs convierten cada type en una excepción. Todas heredan de una clase base y exponen el status HTTP, type, code, param, requestId y docUrl, con los nombres en la convención de cada lenguaje (http_status y request_id en Python).
invalid_request_error- Node
InvalidRequestError - Python
InvalidRequestError authentication_error- Node
AuthenticationError - Python
AuthenticationError permission_error- Node
PermissionError - Python
PermissionDeniedError idempotency_error- Node
IdempotencyError - Python
IdempotencyError rate_limit_error- Node
RateLimitError - Python
RateLimitError api_error- Node
APIError - Python
APIError - sin respuesta
- Node
APIConnectionError - Python
APIConnectionError - clase base
- Node
KuidaError - Python
KuidaError
La verificación de firma de webhooks lanza SignatureVerificationError.
import { Kuida, InvalidRequestError, KuidaError } from "@kuida/sdk";
const kuida = new Kuida("kd_test_…");
try {
await kuida.patients.create({ fullName: "Paciente Demo" });
} catch (err) {
if (err instanceof InvalidRequestError) {
console.log(err.code, err.param); // parameter_missing phone
} else if (err instanceof KuidaError) {
console.log(err.httpStatus, err.requestId);
} else {
throw err;
}
}Qué conviene reintentar
Los errores de red, 409 con idempotency_key_in_use, 429 y los 5xx son transitorios: se reintentan con espera creciente y la misma Idempotency-Key. Los SDKs lo hacen solos, hasta dos veces por defecto. El resto de los 4xx no se resuelve reintentando: hay que corregir el pedido.
Códigos
El docUrl de cada error apunta a la sección de su código en esta página.
parameter_missingHTTP 400 · invalid_request_error
Falta un parámetro obligatorio, o el pedido no tiene cuerpo. param indica cuál (por ejemplo, phone o patient).
Qué hacer: Agregar el parámetro. La referencia de cada operación marca cuáles son obligatorios.
parameter_invalidHTTP 400 · invalid_request_error
Un parámetro tiene un valor no válido: tipo, formato, longitud, un valor fuera del enum, un cursor de paginación que no existe o un dato que no alcanza para identificar al paciente.
Qué hacer: Revisar el valor del parámetro indicado en param; message explica qué falló.
body_invalid_jsonHTTP 400 · invalid_request_error
El cuerpo del pedido no es JSON válido.
Qué hacer: Enviar un JSON válido con el header Content-Type: application/json.
body_too_largeHTTP 413 · invalid_request_error
El cuerpo supera 1 MB.
Qué hacer: Dividir el envío en pedidos más chicos.
batch_too_largeHTTP 413 · invalid_request_error
El lote de POST /v1/events tiene más de 100 eventos.
Qué hacer: Enviar lotes de hasta 100 eventos.
resource_missingHTTP 404 · invalid_request_error
No existe un objeto con ese id en la organización de la clave. También ocurre si el id es de otro tipo (un apt_… donde se espera un pat_…).
Qué hacer: Verificar el id y el prefijo. Cada organización ve solo sus propios objetos.
resource_conflictHTTP 409 · invalid_request_error
El cambio choca con otro objeto; por ejemplo, ya hay otro paciente con ese DNI en la organización.
Qué hacer: Buscar el objeto existente (por ejemplo, GET /v1/patients?dni=…) y trabajar sobre ese.
api_key_missingHTTP 401 · authentication_error
El pedido no trae el header Authorization.
Qué hacer: Enviar Authorization: Bearer kd_live_….
api_key_invalidHTTP 401 · authentication_error
La clave está mal formada o no existe.
Qué hacer: Copiar la clave completa, sin espacios ni saltos de línea. Si se perdió, pedir una nueva.
api_key_revokedHTTP 401 · authentication_error
La clave fue revocada.
Qué hacer: Usar la clave vigente o pedir una nueva a Kuida.
api_key_expiredHTTP 401 · authentication_error
La clave tenía fecha de vencimiento y ya pasó.
Qué hacer: Pedir una clave nueva a Kuida.
scope_missingHTTP 403 · permission_error
La clave no tiene el permiso que exige la operación. message indica cuál.
Qué hacer: Pedir a Kuida una clave con ese permiso. La referencia indica el permiso de cada operación.
service_not_contractedHTTP 403 · permission_error
La organización no tiene contratada la línea de servicio que usa la operación.
Qué hacer: Consultar con el contacto comercial de Kuida. GET /v1/account muestra las líneas activas en serviceLines.
api_version_invalidHTTP 400 · invalid_request_error
El header Kuida-Version pide una versión que no existe.
Qué hacer: Usar una versión vigente o quitar el header para recibir la actual.
idempotency_key_in_useHTTP 409 · idempotency_error
Hay otro pedido en curso con la misma Idempotency-Key.
Qué hacer: Reintentar en unos segundos con la misma clave. Los SDKs lo hacen solos.
idempotency_key_reusedHTTP 400 · idempotency_error
La Idempotency-Key ya se usó con otro método, ruta o cuerpo.
Qué hacer: Generar una clave nueva por operación (un UUID v4). Reusar la clave solo para reintentar el mismo pedido.
rate_limitedHTTP 429 · rate_limit_error
La clave superó 600 pedidos en el minuto en curso.
Qué hacer: Esperar los segundos que indica Retry-After y reintentar. Para altas masivas, usar lotes de eventos.
processing_failedHTTP 500 · api_error
El pedido era válido pero Kuida no pudo completarlo.
Qué hacer: Reintentar con la misma Idempotency-Key. Si se repite, escribir a desarrolladores@kuida.ar con el requestId.
internal_errorHTTP 500 · api_error
Error inesperado de Kuida.
Qué hacer: Reintentar con la misma Idempotency-Key. Si se repite, escribir a desarrolladores@kuida.ar con el requestId.
¿Un error que no se explica acá? Escriba a desarrolladores@kuida.ar con el requestId.