Diagnóstico y recuperación

Cada sección de esta página parte de lo que ves, explica la causa habitual y te dice qué hacer. Para el significado completo de cada número de error, consulta Errores; esta página es su complemento para cuando te preguntas «¿y ahora qué hago?».

Encuentra tu problema

Guarda pruebas útiles

Antes de cambiar nada, anota lo que ha pasado. Hace más rápido cada uno de los pasos siguientes, y es justo lo que necesita el soporte:

• La hora, en UTC si puedes.
• El endpoint al que llamaste, por ejemplo POST /api/v1/jobs/createTask.
• El estado HTTP y el code del cuerpo de la respuesta.
• El request_id: está en el cuerpo de la respuesta y en la cabecera de respuesta X-Request-Id.
• El ID de la tarea, si recibiste uno. Empieza por job_ y también aparece en la página Registros de la consola.

Distingue tres situaciones, porque cada una pide una reacción distinta: la API rechazó expresamente la solicitud (recibiste un error en JSON; no se creó ni se cobró nada), no recibiste ninguna respuesta (un timeout o una conexión cortada; puede que la tarea exista, consulta más abajo), o la tarea se aceptó y falló después (tienes un ID de tarea con state: "failed").

Si una respuesta no es JSON, por ejemplo una página HTML o de texto plano, la envió nuestra red perimetral antes de que la solicitud llegara a la API. Anota el estado HTTP y las primeras líneas del cuerpo. Una página 403 de este tipo suele significar que la solicitud viene de una región a la que no podemos dar servicio; reintentar no lo cambia.

No pongas nunca claves de API, contraseñas, prompts completos ni archivos originales en registros generales ni en solicitudes de soporte.

He pagado, pero el saldo no ha cambiado

• Tarjeta: el saldo solo cambia cuando nos llega la confirmación del procesador de pagos, normalmente en unos segundos. Actualiza Facturación y revisa Órdenes de recarga.
• Criptomonedas: el saldo se añade cuando la red confirma la transacción, normalmente en unos minutos. Si pagas menos del importe indicado, o cuando la página de pago ya ha caducado, el pago no se añade automáticamente.
• Transferencia manual: abre la orden en Órdenes de recarga y envía tu referencia bancaria o el hash de la transacción. Lo comprobamos a mano, normalmente en unas pocas horas.

La lista completa de casos está en Configura tu cuenta → Problemas frecuentes. ¿Sigue sin aparecer? Abre una conversación en Soporte (tema Facturación) con el ID de la orden y, si pagaste con criptomonedas, el hash de la transacción. No envíes nunca números de tarjeta ni contraseñas.

Todas las llamadas devuelven 401 o 403

Empieza con una llamada gratuita que no cambia nada: consultar tu saldo.

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

La primera línea debería mostrar sk-spicy-. Si no muestra nada, la clave no está cargada en esta terminal: vuelve a definirla (consulta Configura tu cuenta). Después lee el msg de la respuesta:

Ninguno de estos errores se arregla reintentando.

Saldo, límites y soporte

• 40201: el saldo disponible no cubre el precio estimado de la tarea. Añade saldo (consulta Configura tu cuenta) y vuelve a enviar la misma solicitud con el mismo Idempotency-Key. Un bono promocional solo paga los modelos que cubre.
• 40202: se alcanzó un límite de gasto, y msg dice cuál. Un límite de la clave (This key has reached its …) se sube en Claves de API → Editar, o se reinicia solo (el diario a las 00:00 UTC, el mensual el día 1 y el acumulado nunca). Un límite del equipo (Workspace … budget has been reached) lo sube en la página Equipo un propietario, un administrador o un gestor de presupuesto. El límite de la plataforma (Platform quota for today is exhausted…) no se puede subir; vuelve a intentarlo después de las 00:00 UTC. Consulta Límites de gasto.
• 429: demasiadas solicitudes. Espera los segundos que indica Retry-After y ve más despacio; lo que más ayuda es usar webhooks en lugar de sondear en bucles rápidos. Si el mensaje es Too many pending uploads…, esperar no sirve: termina las subidas que ya empezaste. Consulta Límites de solicitudes.

Contactar con soporte: abre una conversación en Soporte, dentro de la consola, o escribe a support@spicyapi.ai. Incluye las pruebas de más arriba: la hora, el endpoint, el code, el request_id o el ID de la tarea, lo que esperabas y lo que pasó, y la estructura de tu solicitud sin los valores privados. No envíes nunca una clave de API.

El modelo no aparece o no está disponible

• El modelo no está en tu lista, o recibes 404: llama a GET /api/v1/models con tu clave de API y usa un modelo que tenga enabled y available en true, copiando su ID exactamente. Que un modelo tenga página en el sitio web no demuestra que tu clave pueda llamarlo en este momento. Consulta Modelos.
• 50301: el modelo no puede aceptar tareas en este momento. Reintenta unas pocas veces con pausas cada vez más largas y después para; repetir solicitudes no hace que un modelo no disponible vuelva a funcionar. Actualiza el catálogo, y pregunta a la persona que paga antes de cambiar a otro modelo.
• 40004: el modelo funciona, pero no con esta combinación de ajustes. El msg indica entre paréntesis qué ajuste es. Cambia ese valor (por ejemplo, una resolución o una relación de aspecto) en lugar de reintentar.
• 40301: el modelo existe, pero esta clave no tiene permiso para usarlo; edita los modelos permitidos de la clave.

Entrada no válida o conflicto con la cotización

• 400: compara tu input con el inputSchema actual del modelo en el catálogo: nombres de campo, tipos, valores permitidos y requisitos condicionales. Quita los campos que el modelo no incluye. Vuelve a comprobarlo después de cambiar de modelo, porque cada modelo tiene su propio esquema.
• 40003: un archivo subido no coincide con lo que declaraste al pedir su URL de subida. Pide una URL de subida nueva con el contentType y el tamaño correctos, y vuelve a subirlo.
• 413: el cuerpo de la solicitud es demasiado grande. Sube los medios con el flujo de subida de medios en lugar de incrustarlos.
• 40901: la cotización caducó, la solicitud cambió después de cotizarla o cambió el precio. Pide una cotización nueva, muestra el importe nuevo a la persona que paga y vuelve a confirmarlo. Consulta Cotizaciones.
• Otros 409: se gestionan según la operación. Si una clave de idempotencia ya se usó con un contenido distinto, la solicitud nueva necesita un Idempotency-Key nuevo y correcto, no reintentos sin fin. Consulta Errores para saber cuándo merece la pena reintentar un 409.

El envío agotó el tiempo de espera sin ID de tarea

Un timeout no te dice si la tarea se creó. No te limites a volver a enviarla con una clave de idempotencia nueva: eso puede crear una segunda tarea y un segundo cobro.

Los timeouts del cliente, las pestañas del navegador cerradas y los streams desconectados no cancelan una tarea aceptada, y una tarea aceptada no se puede cancelar.

La tarea falló

Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado, solo si la página del modelo indica expresamente esta excepción. Consulta settled y cost para conocer el importe final.

• No reintentes sin cambiar nada: invalid_request, unsupported_combination, content_rejected (el modelo elegido rechazó el contenido; cambia el prompt o el modelo).
• Merece la pena reintentar tras una pausa: rate_limited, upstream_unavailable, upstream_failed.
• Corrige algo antes: invalid_asset (vuelve a subir el archivo), timeout (prueba con una duración más corta o una resolución más baja), generation_failed (con las mismas entradas suele fallar de la misma manera).

errorMessage explica el motivo para las personas; puede ser el motivo que dio el propio modelo, en inglés. Haz que tu código decida solo a partir de errorCode. La tabla completa está en Errores. Un reintento es una tarea nueva y se vuelve a cobrar si sale bien.

La tarea se queda en cola o en ejecución

Generar lleva tiempo: un video largo puede tardar varios minutos. Cada tarea tiene un plazo en el servidor, que recordInfo devuelve como deadlineAt:

• Antes de deadlineAt: sigue esperando el callback, o sondea recordInfo con pausas cada vez más largas (no cada segundo).
• Después del plazo: la tarea termina sola como expired con errorCode: "timeout", y se te devuelve todo lo retenido. No tienes que cancelar nada; además, las tareas aceptadas no se pueden cancelar.

Si una tarea sigue en running mucho después de su deadlineAt, contacta con soporte indicando el ID de la tarea.

La subida funcionó, pero la entrada se rechaza

• Te saltaste la confirmación. Un PUT correcto del archivo no basta: llama a files/{fileId}/commit y pasa la URI spicy:// devuelta en el campo de entrada del modelo. No pases nunca la propia uploadUrl.
• El archivo no coincide con el ticket. Comprueba el Content-Type declarado, el tamaño y el formato; si no coinciden, recibes 40003.
• Ha caducado. Un archivo subido se puede usar hasta el expiresAt de la respuesta de su confirmación: 1 día de forma predeterminada, o menos si tu cuenta borra las subidas cuando termina la tarea. Por eso, reintentar una tarea puede exigir una subida nueva.
• Pertenece a otra cuenta. Una URI spicy:// solo funciona con claves de la cuenta que subió el archivo.

Consulta Carga y descarga de medios para ver el flujo de subida completo.

Falta el callback o caducó la descarga

No llegó ningún callback:

1. Comprueba que callBackUrl es una dirección https:// accesible desde internet. No se acepta http:// a secas.
2. Comprueba que tu receptor verifica la firma sobre los bytes originales de la solicitud, antes de interpretar el JSON, y que responde rápido con un 2xx. El trabajo lento va en tu propia cola. Si la clave de firma se rotó hace poco, el receptor tiene que usar la nueva: no hay periodo de transición. Consulta Webhooks.
3. Revisa el historial de entregas en Webhooks, dentro de la consola, donde también puedes reintentar una entrega.
4. Mientras tanto, consulta la tarea con recordInfo: el sondeo siempre es una alternativa válida. Consulta Webhooks.

Los callbacks pueden llegar más de una vez o con retraso, así que elimina los duplicados antes de dar un pedido por completado.

El enlace de descarga o el archivo ya no existen:

• Un enlace de descarga dura 20 minutos. Si el resultado se sigue guardando, pide un enlace nuevo; actualizar un enlace antiguo no funciona.
• Si el resultado todavía se está copiando al almacenamiento, espera unos segundos y vuelve a preguntar.
• Los resultados se guardan como máximo unos 14 días, y menos si tu cuenta usa un ajuste de conservación más corto. Cuando contentState es expired o purged, el archivo no se puede recuperar: vuelve a ejecutar el modelo. Consulta Conservación.

El stream termina antes de tiempo

Comprueba el estado HTTP y el Content-Type antes de interpretar el stream según tu protocolo. Los fragmentos que llegan por la red no son eventos completos, y una conexión cerrada no indica éxito: busca el evento final del protocolo, cualquier evento de error y tu propio plazo de la aplicación. No des por hecho que un stream desconectado sale gratis ni que se puede volver a enviar sin costo: el consumo válido registrado antes de la desconexión puede cobrarse. Guarda el request_id y revisa tus registros de consumo. Consulta Texto y streaming.

Permisos del equipo

• No puedes crear una clave. El selector de ámbito, arriba del todo en la barra lateral izquierda de la consola, tiene seleccionado un equipo en el que tu rol es Gestor de presupuesto o Solo lectura. Para crear claves hace falta el rol Propietario, Administrador o Desarrollador. Cambia a tu ámbito Personal o pide a un administrador del equipo el rol Desarrollador.
• Ves una tarea, pero no su prompt ni su resultado. Los gestores de presupuesto y los miembros de solo lectura solo ven el estado, el costo y el consumo.
• No puedes aceptar una invitación. Inicia sesión con exactamente la misma dirección de correo a la que se envió la invitación. Las invitaciones caducan a los 7 días; si la tuya ha caducado, pide una nueva.
• Una clave del equipo se detuvo con 40201. Las claves de equipo gastan el saldo del propietario del equipo, así que es el propietario quien tiene que añadir saldo.

Consulta Consola y espacios de trabajo para ver los roles y los límites de los equipos.

No puedo emitir una factura

• Tus datos están incompletos. Una factura necesita un nombre (el de tu empresa o el tuyo), la línea 1 de la dirección, la ciudad y el país, que se introducen una sola vez arriba del todo en Facturación → Facturas.
• Un carácter no se puede imprimir. En una factura solo pueden aparecer caracteres latinos, griegos y cirílicos. Escribe el nombre de una empresa japonesa o coreana en su forma romanizada registrada.
• Ya existe. Cada recarga pagada y cada mes cerrado se pueden facturar una sola vez; descarga el documento existente. Para corregir los datos, elige Reemitir en él.
• El mes no está disponible. Solo los meses ya terminados en los que gastaste algo pueden tener un detalle de consumo.

Consulta Facturación para ver las facturas y los detalles de consumo.

Flujos relacionados

Errores · Integración en producción · Idempotencia · Carga y descarga de medios · Webhooks · Texto y streaming · Configura tu cuenta