Guías
Errores
El formato de los errores y qué hacer con cada código.
Todos los errores de la API son una respuesta application/problem+json, en el formato RFC 9457:
{
"type": "https://piqline.com/docs/api/errors#insufficient_scope",
"title": "Scope insuffisant",
"status": 403,
"code": "insufficient_scope",
"detail": "searchWeb demande le scope explore.",
"request_id": "8c0c051b-c3e6-4fa0-8b98-0aa227cf3c2a",
"missing_scopes": ["explore"]
}| Campo | Significado |
|---|---|
type | la URL de la sección de esta página que describe el error |
title | un título corto, en francés |
status | el estado HTTP |
code | el identificador estable del error: prueba este |
detail | una explicación legible, en francés, que puede cambiar entre versiones |
request_id | el ID de la petición, también en la cabecera X-Request-Id |
Según el error, se añaden otros campos: missing_scopes, issues.
Cuando nos escribas, cita el request_id. Permite encontrar la petición en nuestros registros y, si la clave era válida, en el historial de Ajustes → API y MCP. El formulario está en la página de contacto.
Códigos#
missing_key#
401 · Falta la clave de API
Causa. La petición no incluye ninguna clave.
Qué hacer. Envía Authorization: Bearer piq_live_… (o x-api-key).
invalid_key#
401 · Clave de API no válida
Causa. La clave tiene un formato incorrecto (copia truncada o reescrita), es desconocida, está revocada o caducada, o su creador ha abandonado el workspace. detail distingue un problema de formato de un problema de estado.
Qué hacer. Revisa la copia. Si la clave está revocada o caducada, crea una nueva en Ajustes → API y MCP.
insufficient_scope#
403 · Scope insuficiente
Causa. A la clave le falta un scope que exige la ruta o la herramienta. missing_scopes los lista.
Qué hacer. Crea una clave con esos scopes. Una clave existente conserva sus scopes: no se pueden cambiar.
forbidden#
403 · Prohibido
Causa. El rol del creador de la clave no da acceso a esta herramienta o agente.
Qué hacer. Crea la clave desde una cuenta que tenga el rol requerido (propietario o administrador para las herramientas de escritura y de acción, y para el agente onboarding).
not_found#
404 · No encontrado
Causa. Ruta, herramienta o agente desconocidos. Las tarjetas interactivas del chat (askUser, proposeSources, proposeBoard…) no son herramientas invocables.
Qué hacer. Lista los nombres válidos con GET/api/v1/tools y GET/api/v1/agents.
invalid_input#
422 · Entrada no válida
Causa. El cuerpo no es JSON válido, o la entrada no coincide con el esquema de la herramienta. issues señala cada campo erróneo (path, message).
Qué hacer. Compara tu cuerpo con el input_schema de la herramienta (GET/api/v1/tools/{nom}).
tool_error#
422 · Error de herramienta
Causa. La herramienta rechazó la petición por un motivo propio de tus datos, por ejemplo un elemento que no existe en este workspace. detail indica el motivo.
Qué hacer. Corrige la entrada según detail. La misma llamada da la misma respuesta mientras no cambie nada.
rate_limited#
429 · Demasiadas peticiones
Causa. La clave ha superado su límite por minuto.
Qué hacer. Espera el número de segundos indicado en la cabecera Retry-After y vuelve a intentarlo. Espacia tus llamadas.
quota_exceeded#
429 · Cuota diaria alcanzada
Causa. La clave ha alcanzado su tope diario de peticiones. El contador se reinicia cada día a medianoche UTC.
Qué hacer. Vuelve a intentarlo después de medianoche UTC. Para subir el tope, escríbenos desde la página de contacto.
budget_exhausted#
402 · Créditos mensuales agotados
Causa. El workspace de la clave ha alcanzado su tope mensual de créditos. Todo lo que gasta (agentes, herramientas de pago, recogida) se rechaza antes de la llamada, y un turno de agente en curso se detiene al llegar al tope. detail indica la fecha de reanudación.
Qué hacer. Espera la fecha de reanudación indicada en detail, o pide a un propietario del workspace que suba el tope.
plan_restricted#
403 · No incluido en el plan
Causa. El plan del workspace de la clave no permite esta petición: no abre la API, o la abre en solo lectura y la petición escribe, se suscribe, o inicia una investigación o un agente. plan indica el plan y api_access el acceso (none, read).
Qué hacer. Pide a Piqline un plan que abra el acceso que necesitas: Équipe para lectura, Business para acceso completo.
unavailable#
503 · Servicio no disponible
Causa. Un servicio del que depende la petición no responde: verificación de la clave, modelo del agente o proveedor.
Qué hacer. Vuelve a intentarlo con una espera creciente. Si el error persiste, cita request_id cuando nos escribas.
not_configured#
503 · No configurado
Causa. La API no está configurada en el servidor: falta una variable de entorno.
Qué hacer. Cita request_id cuando nos escribas: solo Piqline puede resolver este caso.
internal#
500 · Error interno
Causa. Error inesperado por parte de Piqline. detail es vago a propósito.
Qué hacer. Vuelve a intentarlo. Si el error persiste, cita request_id cuando nos escribas.