Skip to main content
La API de Pioneer utiliza códigos de estado HTTP estándar para comunicar el resultado de cada solicitud. Los códigos en el rango 2xx indican éxito. Los códigos en el rango 4xx indican un problema con tu solicitud que puedes corregir. Los códigos en el rango 5xx indican un problema del lado del servidor.

​
Formato de la respuesta de error

La mayoría de las respuestas de error devuelven un cuerpo JSON con un campo detail:
Algunas familias de respuestas usan una forma diferente:
  • Denegaciones de facturación (402, algunos 403) devuelven {"code", "message", "resolution_url"} en lugar de detail — consulta 402 y 403 más abajo.
  • Respuestas de límite de velocidad (429) añaden los campos code y scope junto a detail, además de los encabezados X-RateLimit-Scope y X-RateLimit-Code — consulta 429 más abajo.
  • Errores del servidor no controlados (500) devuelven {"error", "message"} en lugar de detail.
  • Las solicitudes a los endpoints compatibles con OpenAI (/v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings) reciben una envoltura con forma de OpenAI {"error": {"code", "type", "param", "message"}}, y las solicitudes que llevan un encabezado anthropic-version reciben una envoltura con forma de Anthropic {"type": "error", "error": {"type", "message"}} en lugar de las formas genéricas anteriores.

​
Códigos de estado

​
400 — Solicitud incorrecta

La solicitud en sí está mal formada — JSON no válido, o un parámetro de consulta/ruta con un tipo incorrecto. Cómo solucionarlo: Confirma que el cuerpo de tu solicitud sea JSON válido y que los parámetros de consulta/ruta coincidan con los tipos documentados en la referencia del endpoint.

​
401 — No autorizado

Tu solicitud no incluyó una clave de API válida, la clave ha sido revocada, o tu cuenta ha sido bloqueada por revisión de facturación o fraude. Cómo solucionarlo: Verifica que el encabezado X-API-Key esté presente y contenga tu clave actual. Si revocaste la clave recientemente, genera una nueva en Settings → API Keys. Si tu cuenta está bloqueada, contacta a support@pioneer.ai. Consulta Autenticación para instrucciones de configuración.

​
402 — Pago requerido

Una respuesta 402 significa que tu cuenta se ha quedado sin créditos utilizables o que se requiere una acción de facturación antes de poder ejecutar inferencia. Todas las llamadas a la API fallarán hasta que añadas créditos o mejores tu plan. Visita Settings → Billing o consulta Planes y precios para resolverlo.
Tu cuenta no tiene créditos suficientes para completar la solicitud. El campo code del cuerpo de la respuesta te indica qué caso se aplica — normalmente out_of_credits (tus créditos incluidos están agotados y no hay saldo pagado utilizable) o direct_model_requires_credits (los créditos incluidos del plan son solo para el router; llamar a un modelo directamente en lugar de a través de pioneer/auto requiere un saldo de créditos pagados). Cómo solucionarlo: Inicia sesión en pioneer.ai, ve a Settings → Billing y recarga tu saldo o mejora tu plan. Consulta Límites de créditos y tope de gasto por excedente para conocer cómo funcionan los límites de créditos y la facturación por excedente.

​
403 — Prohibido

Tu equipo ha alcanzado el gasto máximo mensual por excedente de su plan (code: "credit_ceiling_reached"), o tu cuenta necesita un método de pago verificado antes de ejecutar inferencia (code: "card_required"). Cómo solucionarlo: Para una denegación por tope de gasto, mejora tu plan en Settings → Billing para aumentar el tope. Para una denegación por verificación de tarjeta, añade un método de pago válido. Ambas respuestas incluyen un resolution_url que apunta directamente a la página para resolverlas.

​
404 — No encontrado

El recurso que solicitaste no existe. Esto puede ocurrir cuando el nombre de un dataset, un ID de trabajo de entrenamiento, un ID de evaluación, un ID de proyecto o un ID de modelo está mal escrito o ha sido eliminado. Cómo solucionarlo: Verifica dos veces el ID o el nombre en la ruta o el cuerpo de la solicitud. Usa el endpoint GET de listado correspondiente (por ejemplo GET /felix/training-jobs, GET /base-models) para confirmar que el recurso existe.

​
409 — Conflicto

El modelo existe en el catálogo pero no puede servirse actualmente — por ejemplo, un modelo base solo para entrenamiento solicitado para inferencia directa, o un despliegue on-demand que no ha terminado de aprovisionarse después de completarse un trabajo de entrenamiento. Cómo solucionarlo: Consulta supports_inference y supports_on_demand_inference para el modelo a través de GET /base-models, o reintenta después de que el despliegue termine de aprovisionarse.

​
413 — Carga útil demasiado grande

El cuerpo de la solicitud — normalmente una carga de archivo para una evaluación o dataset — excede el límite de tamaño del endpoint. Cómo solucionarlo: Revisa la referencia del endpoint para conocer su límite de tamaño de carga y divide o comprime la carga útil antes de reintentar.

​
422 — Entidad no procesable

El cuerpo de la solicitud no superó la validación. Falta un campo obligatorio, un campo tiene el tipo incorrecto, o un valor está fuera del rango aceptado. Cómo solucionarlo: Revisa el message del error para identificar el campo específico que falló. Las causas comunes incluyen:
  • Omitir base_model en POST /felix/training-jobs
  • Pasar un task_type no admitido a POST /generate
  • Enviar menos de 1 o más de 1.000 cadenas en el arreglo inputs para endpoints de etiquetas existentes

​
425 — Demasiado pronto

El despliegue on-demand solicitado todavía se está calentando (arranque en frío) y aún no está listo para servir inferencia. Cómo solucionarlo: Respeta el encabezado Retry-After y reintenta después del retardo indicado. Esto es esperable en la primera solicitud contra un despliegue on-demand recién aprovisionado.

​
429 — Demasiadas solicitudes

Has superado un límite de velocidad de solicitudes para este endpoint. La respuesta incluye un encabezado Retry-After, además de los encabezados X-RateLimit-Scope y X-RateLimit-Code que identifican qué límite alcanzaste — el cuerpo JSON contiene los campos code y scope correspondientes junto a detail. Cómo solucionarlo: Respeta el valor de Retry-After y espera antes de reintentar. Consulta Límites de velocidad para conocer los límites por endpoint y un patrón de código de reintento. Ten en cuenta que las denegaciones por créditos y por excedente devuelven 402/403, no 429 — consulta Límites de créditos y tope de gasto por excedente.

​
451 — No disponible por motivos legales

El modelo solicitado no está disponible para tu cuenta debido a restricciones de control de exportaciones o sanciones en tu región. Cómo solucionarlo: Consulta las Preguntas frecuentes para ver la lista actual de regiones restringidas y las políticas específicas de cada proveedor. Si crees que tu acceso fue restringido incorrectamente, contacta con soporte.

​
500 — Error interno del servidor

Ocurrió un error inesperado en los servidores de Pioneer. Esto no es causado por tu solicitud. El cuerpo usa los campos error y message en lugar de detail:
Cómo solucionarlo: Espera un momento y reintenta. Si el error persiste, consulta status.pioneer.ai para ver el estado del servicio en vivo o contacta con soporte.

​
503 — Servicio no disponible

Una dependencia que la solicitud necesitaba — verificación de facturación, o un endpoint de estado/métricas de un proveedor — está temporalmente no disponible. Cómo solucionarlo: Espera un momento y reintenta. Si el error persiste, consulta status.pioneer.ai para ver el estado del servicio en vivo o contacta con soporte.

​
529 — Sobrecargado (solo endpoint compatible con Anthropic)

POST /v1/messages replica la propia respuesta overloaded_error de Anthropic cuando la capacidad ascendente de Claude está temporalmente saturada. Cómo solucionarlo: Reintenta con backoff, igual que harías para un 429 o 503.