Saltar al contenido

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:

JSON
{
  "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"]
}
CampoSignificado
typela URL de la sección de esta página que describe el error
titleun título corto, en francés
statusel estado HTTP
codeel identificador estable del error: prueba este
detailuna explicación legible, en francés, que puede cambiar entre versiones
request_idel 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.

¿Tienes una pregunta sobre la API o has encontrado un error en esta página? Escríbenos.