Solución de problemas

Busque el síntoma en la categoría que corresponda. La tabla completa de códigos de estado, las reglas de reintento y qué incluir al reportar un problema están en Códigos de error y reintentos.

El gateway devuelve texto en chino simplificado, chino tradicional, inglés, japonés o español según el encabezado Accept-Language, y en inglés cuando no se envía ese encabezado. Las tablas citan el texto que devuelve con Accept-Language: es.

Claves, saldo y permisos

Síntoma	Causa	Qué hacer
401 "Falta la clave de API" "Clave de API no válida" "La clave de API ha caducado"	Clave ausente, copiada incompleta o con espacios, o eliminada, deshabilitada o caducada	Vuelva a copiar la clave completa desde Claves API en la consola; cree una nueva si hace falta
402 "Saldo insuficiente" "Cuota de la clave de API agotada" "Cuota del miembro agotada" "Cuota del departamento agotada"	Saldo de la cuenta, cuota de esta clave o cuota de miembro o departamento insuficiente	Añada fondos o ajuste la cuota antes de reintentar; el 402 no se resuelve solo, no reintente en bucle
Un envío de video devuelve 402 "Insufficient balance: available …"	El saldo reservado al enviar la tarea de video es insuficiente	Añada fondos y vuelva a enviar; no reintente en bucle
403 "Esta cuenta ha sido deshabilitada" "Esta cuenta de miembro ha sido deshabilitada" "Este miembro no tiene permiso para usar el grupo vinculado a esta clave de API" "La clave de API no está vinculada a ningún grupo, contacte al administrador" "La generación de imágenes no está habilitada en el grupo actual"	Configuración de cuenta, miembro o grupo	Contacte al administrador; no reintente
404 "El grupo al que pertenece esta clave de API ha sido dado de baja y ya no atiende solicitudes…"	El grupo de esta clave fue descontinuado	Cree una clave en un grupo disponible en la consola y reemplace la anterior

Modelos y rutas

Síntoma	Causa	Qué hacer
404 "El grupo actual no admite el modelo solicitado: X" "El grupo al que pertenece esta clave de API no ofrece el modelo solicitado…"	El ID no está en ninguno de los grupos de esta clave, está mal escrito o es un ID retirado que quedó en la configuración del cliente	Llame a `GET /v1/models` con esta clave y copie un ID completo; si no aparece, añada a la clave el grupo del modelo. No reintente automáticamente
404 "La plataforma actual no admite esta ruta de API"	Una clave Claude llamó a un endpoint del protocolo OpenAI	Cambie Claude al protocolo Anthropic
Igual que arriba	El Base URL de Anthropic tiene un `/v1` de más (queda `/v1/v1/messages`)	Quite `/v1` del Base URL
Igual que arriba	La plataforma no expone esa ruta, como `/v1/dashboard/billing/*`, `/v1/files`, `/v1/batches`, `/v1/embeddings`	Consulte el saldo con `GET /v1/usage` o en la consola
Igual que arriba	La búsqueda web de Codex llamó a `/v1/alpha/search`	Este 404 no afecta las conversaciones
Un endpoint de video devuelve 404 "La plataforma actual no admite esta ruta de API"	La ruta de video es incorrecta	Según la API de video: envíe con `POST /v1/video/generate` y consulte con `GET /v1/video/tasks/{task_id}`

Contenido de la solicitud

Síntoma	Causa	Qué hacer
400 "No se pudo leer el cuerpo de la solicitud" "El cuerpo debe ser un objeto JSON con tipos de campo válidos" "Falta el campo obligatorio: model" "messages debe ser un array no vacío"	El cuerpo está incompleto o tiene campos no válidos	Revise el JSON y el `Content-Type`
413 "El cuerpo de la solicitud supera el límite de tamaño (60 MB)"	El cuerpo supera 60 MB, normalmente por imágenes o video en base64	Comprima los archivos grandes, o envíe una URL cuando el modelo lo admita
400 por exceder la longitud de contexto (el texto exacto varía según el modelo)	Historial, adjuntos y `max_tokens` superan juntos el contexto del modelo	Recorte el historial o inicie una conversación nueva, y reduzca `max_tokens`
400 "Invalid `signature` in `thinking` block" "duplicate `thinking.signature`"	El historial de thinking de Claude fue reescrito, concatenado o duplicado	Devuelva el thinking anterior tal cual (con signature), sin reescribirlo, combinarlo ni cambiar de modelo; si persiste, reinicie sin thinking
400 "No tool call found for function call output" "No tool output found for function call"	Resultados y llamadas a herramientas no están emparejados: `tool_call_id` / `call_id` no coinciden o falta uno	Devuelva un resultado por cada llamada con su ID sin cambios; al recortar el historial, elimine cada par junto
400 "Unsupported parameter: …"	El modelo no acepta un parámetro que envió	Elimínelo; en la Responses API limite la salida con `max_output_tokens`, no con `max_tokens`

Imágenes y video

Síntoma	Causa	Qué hacer
400 contenido rechazado por una política de seguridad (por ejemplo "Your request was rejected by the safety system.")	El prompt o un recurso de referencia activó la política de seguridad de contenido del modelo	Modifique el prompt o el recurso; reenviar la misma solicitud será rechazado de nuevo
400 parámetros de imagen inválidos (por ejemplo "size … is not valid")	Tamaño, nivel o cantidad fuera de lo que admite ese modelo	Ajuste el valor según la API de imágenes
400 "media_download_failed"	La URL de una imagen o video de referencia no es pública	Use una URL HTTP(S) descargable sin iniciar sesión
400 "InputImageSensitiveContentDetected.PrivacyInformation"	Seedance 2.0 aplica detección de privacidad a fotos de personas reales enviadas directamente	Súbala primero como asset con `POST /v1/sd/assets` y referénciela como `asset://asset-id`; vea la API de video
El sondeo de una tarea asíncrona devuelve `status: "failed"` (por ejemplo "the prompt was rejected by content moderation; rephrase it and submit again")	Motivo en `error.message`, sin `code`, sin facturar	Corrija lo que indica el mensaje y reenvíe; vea Códigos de error y reintentos
Necesita el cargo real de una tarea asíncrona	Viene en la consulta de la tarea cuando termina	Lea en la raíz `usage.cost_usd` (el importe en USD descontado de su saldo), `usage.cost` (el mismo cargo en CNY) y `usage.currency` (`0` si falló sin cargo); las tareas finalizadas de una lista también los llevan; vea la API de video

Límites, tiempos de espera e interrupciones

Síntoma	Causa	Qué hacer
429 "Se alcanzó el límite de concurrencia del usuario, inténtelo de nuevo más tarde" "Se alcanzó el límite de concurrencia de la clave de API, inténtelo de nuevo más tarde"	Las solicitudes en curso superan el límite de concurrencia de la cuenta o de la clave	Encole y limite en el cliente, y reintente según `Retry-After`; límites en Concurrencia, tiempos de espera y facturación
429 "… están sujetas a límite de tasa en este momento, inténtelo de nuevo más tarde" 502 "El servicio … no está disponible temporalmente, inténtelo de nuevo más tarde" 503 "No hay ninguna … disponible en este momento, inténtelo de nuevo más tarde" 503 "La solicitud no se pudo completar en este momento, inténtelo de nuevo más tarde" 504 "La solicitud … agotó el tiempo de espera, inténtelo de nuevo más tarde" 503 "El servicio de autenticación no está disponible temporalmente, inténtelo de nuevo"	El servicio no está disponible temporalmente o la respuesta superó el tiempo de espera	Reintente con `Retry-After` o retroceso exponencial, o cambie a un modelo de la misma familia. Si dura más de 10 minutos, contáctenos con el `X-Request-ID` de la respuesta
503 "Esta conversación está vinculada a una sesión con estado que ya no puede reanudarse…"	La sesión original ya no puede continuar	Inicie una conversación nueva sin `previous_response_id`
La solicitud se corta a mitad de camino y se registra como 499	Cancelación manual o tiempo de lectura del cliente agotado (openai-python: 600 s por defecto; otros clientes varían)	Use streaming para salidas largas y aumente el tiempo de lectura del cliente
Llega un evento de error a mitad del streaming (por ejemplo "Response stream interrupted, please retry") o se cae la conexión	El fallo ocurrió con la salida ya iniciada; no se puede reanudar en el mismo stream	Descarte el fragmento recibido y reenvíe la solicitud completa

Entorno local

Síntoma	Causa	Qué hacer
"node / npm is not recognized"	Node.js no está instalado o no está en `PATH`	Reinstale desde nodejs.org (opciones predeterminadas en Windows), luego cierre y vuelva a abrir la terminal
PowerShell bloquea la ejecución de scripts	Restricciones de la política de ejecución de Windows	Prefiera el comando de configuración con un clic de la consola; o ejecute `Set-ExecutionPolicy RemoteSigned` como administrador

¿Sigue atascado después de revisar estas tablas? Contáctenos con el nombre del cliente, ID del modelo, hora aproximada, código de estado HTTP, el X-Request-ID de los encabezados de respuesta y una captura de pantalla con la clave oculta.

Próximos pasos

Códigos de error y reintentos: la tabla completa de códigos de estado y las reglas de reintento
Concurrencia, tiempos de espera y facturación: los límites detrás de los 429 y los tiempos de espera
Preguntas frecuentes: dudas comunes sobre direcciones, claves y facturación