Errores y paginación
La forma de un error, qué hacer con cada código, y cómo recorrer una lista.
Los errores
Un error tiene siempre la misma forma:
{ "error": { "code": "window_closed", "message": "Pasaron más de 24 horas…" } }code es estable: ramifica por él. message es prosa para quien lee el registro. Un código que tu código no conozca trátalo como un fallo genérico: añadir códigos no rompe la versión 1. La lista completa está en la referencia.
401 unauthorized: falta la clave, o ya no vale (revocada o caducada).403 forbidden: la clave no tiene el permiso de esa operación. Se arregla en la pantalla de la clave.402 subscription_restricted: la suscripción tiene un pago pendiente. No se arregla desde el código.400 invalid_request: un campo falta o no vale. El mensaje nombra los campos, nunca los valores.429 rate_limited: se acabó el cupo por minuto. Espera lo que diga la cabeceraretry-after.500 internal_error: un fallo nuestro. Reintenta con espera; la cabecerax-request-idnos ayuda a encontrarlo.
La paginación
Las listas vienen de más reciente a más vieja, 50 por página (hasta 100 con limit). Si hay más, la respuesta trae nextCursor: pásalo tal cual en ?cursor= para la siguiente. Es opaco: no lo construyas a mano. Así no se pierden ni se repiten filas aunque entren datos nuevos mientras recorres.
Reintentos sin duplicados
Abrir un caso y mandar un mensaje piden idempotencyKey. Un tiempo de espera agotado no dice si la operación se hizo: reintenta con la misma clave y Koonni devuelve lo que ya hizo, en vez de hacerlo otra vez.