Errores
La Partner API usa códigos de estado HTTP estándar y devuelve el detalle del error en el body JSON. Esta página cubre todos los códigos que puede devolver y cómo reaccionar a cada uno.
Formato del error
Sección titulada «Formato del error»La mayoría de los errores devuelven un objeto con detail (texto legible):
{ "detail": "API key inválida o expirada"}Los errores de validación (422) devuelven detail como una lista, una entrada por campo inválido — es el formato estándar de FastAPI:
{ "detail": [ { "loc": ["body", "email"], "msg": "value is not a valid email address", "type": "value_error.email" } ]}loc: ubicación del campo (body,query,path+ nombre).msg: descripción legible.type: código de error de máquina, útil para mapear mensajes propios.
Códigos de estado
Sección titulada «Códigos de estado»| Código | Significado | Qué hacer |
|---|---|---|
200 / 201 / 204 | Éxito | — |
400 | Petición inválida | Revisa el body y los parámetros. También: plan inexistente, period inválido, email o subdominio ya usados, tenant no activo en /chat, archivo de tipo o tamaño no permitido, y protocolos fuera de los límites (ver abajo). |
401 | API key inválida o expirada | Verifica el header Authorization. Regenera la key si hace falta. |
403 | Sin acceso Partner | Tu cuenta aún no está habilitada como partner, o está suspendida. Contacta a soporte. |
404 | Recurso no encontrado | El tenant_id o source_id no existe o no te pertenece. |
409 | Conflicto | El recurso ya existe o falta un prerrequisito (p. ej. registrar un webhook sin una API key activa). |
422 | Error de validación | Revisa la lista detail para ver qué campo falló. |
429 | Rate limit excedido | Superaste 120 requests/minuto. Espera y reintenta con backoff. |
500 | Error interno | Reintenta con backoff. Si persiste, contacta a soporte con la hora del request. |
Límites al cargar protocolos
Sección titulada «Límites al cargar protocolos»POST /partner/tenants/{tenant_id}/kb/protocols valida cada protocolo y es todo o nada: si uno no cumple, no se carga ninguno y la respuesta es 400 con el motivo.
| Límite | Valor |
|---|---|
| Protocolos activos por tenant | 12 |
title (la situación) | 120 caracteres |
content (el procedimiento) | 800 caracteres |
| Protocolos por request | 50 (si se supera, 422) |
El campo created de la respuesta cuenta los protocolos realmente creados; puede ser menor que los enviados si alguno ya existía.
Rate limiting
Sección titulada «Rate limiting»El límite es de 120 requests por minuto y por API key (ventana fija). Al excederlo recibes 429:
{ "detail": "Rate limit excedido: máximo 120 requests/minuto por API key."}Recomendaciones:
- Implementa backoff exponencial ante un
429(p. ej. 1s, 2s, 4s). - Para cargas grandes (alta de muchos tenants, carga masiva de KB), serializa o agrupa las llamadas en lugar de dispararlas en paralelo.
- El rate limit se cuenta por API key, no por tenant.
Patrón de manejo recomendado
Sección titulada «Patrón de manejo recomendado»import timeimport requests
def call_with_retry(method, url, headers, json=None, max_retries=4): for attempt in range(max_retries): resp = requests.request(method, url, headers=headers, json=json) if resp.status_code == 429 or resp.status_code >= 500: time.sleep(2 ** attempt) # backoff: 1s, 2s, 4s, 8s continue if not resp.ok: # 4xx no recuperable: registra detail y corta raise RuntimeError(f"{resp.status_code}: {resp.json().get('detail')}") return resp.json() if resp.content else None raise RuntimeError(f"Agotados {max_retries} intentos para {url}")- Reintenta solo
429y5xx(transitorios). - No reintentes
4xxde cliente (400,401,403,404,422): son errores de tu request, reintentar no los arregla.