EssevinSolución de problemas
Diagnostique rápidamente errores de protocolo, clave, modelo y entorno.
Busque la fila que coincide con lo que está viendo.El gateway devuelve texto en chino, inglés u otro idioma según el encabezado Accept-Language; usa inglés de forma predeterminada cuando no se envía ese encabezado.
| Síntoma | Causa | Qué hacer |
|---|---|---|
| 401 "Falta la clave de API" / "Clave de API no válida" / "La clave de API ha caducado" | No se envió ninguna clave, se copió de forma incompleta o con espacios adicionales, o la clave fue eliminada, deshabilitada o expiró | Vuelva a copiar la clave completa desde Claves API en la consola; cree una nueva si es necesario |
| 402 "Saldo insuficiente" / "Cuota de la clave de API agotada" | Los créditos de la suscripción de este mes se agotaron, la cuota propia de esta clave se agotó, o la cuenta no tiene un período de suscripción activo | Espere al reinicio mensual de créditos o aumente la cuota de esta clave antes de reintentar; el 402 no se resuelve por sí solo, no reintente en bucle |
| 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" / "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" | El modelo está temporalmente no disponible o la respuesta superó el tiempo de espera | Reintente usando Retry-After o retroceso exponencial, o cambie a otro modelo de la misma familia; si persiste más de 10 minutos, contáctenos con el X-Request-ID de los encabezados de respuesta |
| La solicitud se desconecta a mitad de camino y se registra como 499 | El cliente se desconectó antes de completarse: cancelación manual, o el tiempo de espera de lectura del propio cliente se cumplió primero (openai-python usa 600 segundos por defecto; otros clientes varían) | Cambie a streaming para salidas largas y aumente el tiempo de espera de lectura del cliente |
| Llega un evento de error a mitad de una respuesta en streaming (por ejemplo "Response stream interrupted, please retry") o se cae la conexión | El fallo ocurrió después de que ya había comenzado la salida, por lo que el stream no se puede reanudar en el mismo punto | Descarte el fragmento parcial recibido y reenvíe la solicitud completa |
| 404 "El grupo actual no admite el modelo solicitado: X" / "El grupo al que pertenece esta clave de API no ofrece el modelo solicitado…"; 400 "… is not a valid model ID" | El ID de modelo no está en el grupo de esta clave, está mal escrito, o un ID retirado sigue en caché en la configuración de su cliente | Llame a GET /v1/models con esta clave y copie un ID completo de la respuesta; si no aparece, use una clave de un grupo que lo incluya. No reintente automáticamente |
| 404 "Model "X" is not supported by any configured account in this group" | El modelo no puede atender solicitudes de este grupo en este momento | Llame primero a GET /v1/models con esta clave: si el modelo aparece, trátelo como el caso 502 / 503 anterior; si no, cambie el ID de modelo o use una clave de otro grupo |
| 404 "La plataforma actual no admite esta ruta de API" | La ruta no pertenece al grupo de esta clave: una clave Claude llamó a un endpoint del protocolo OpenAI; el Base URL de Anthropic tiene un /v1 de más (queda como /v1/v1/messages); o la ruta no la expone la plataforma, como /v1/dashboard/billing/*, /v1/files, /v1/batches, /v1/embeddings, o la búsqueda web de Codex en /v1/alpha/search | Cambie Claude al protocolo Anthropic sin /v1 en el Base URL; consulte el consumo con GET /v1/usage o en la consola; el 404 de la búsqueda web no afecta las conversaciones normales |
| 400 "No se pudo leer el cuerpo de la solicitud"; 413 "El cuerpo de la solicitud supera el límite de tamaño (60 MB)" | El cuerpo de la solicitud está incompleto, o supera los 60 MB (normalmente imágenes o video en base64) | Revise el JSON y el Content-Type; comprima los archivos grandes primero, o envíe una URL en su lugar cuando el modelo lo admita |
| 400 por exceder la longitud de contexto (el texto exacto varía según el modelo) | El historial de la conversación, los adjuntos y max_tokens superan juntos la ventana de contexto del modelo | Recorte el historial o inicie una nueva conversación, 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 bloque de thinking del turno anterior del asistente exactamente como se recibió (incluida su signature); nunca lo reescriba, combine ni reutilice entre modelos. Si no puede solucionarlo, reinicie la conversación sin historial de thinking |
| 400 "No tool call found for function call output" / "No tool output found for function call" | Los resultados de herramientas y las llamadas a herramientas no están emparejados: tool_call_id / call_id no coinciden, o falta uno de los dos | Devuelva exactamente un resultado por cada llamada a herramienta y reenvíe su ID sin cambios; al recortar el historial, elimine ambos lados de cada par juntos |
| 400 "Unsupported parameter: …" | El modelo no acepta un parámetro que envió | Elimine ese parámetro; en la Responses API, limite la longitud de salida con max_output_tokens, no con max_tokens |
| 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 antes de reenviar; reenviar la misma solicitud sin cambios será rechazado de nuevo |
| 400 parámetros de imagen inválidos (por ejemplo "size … is not valid") | El tamaño, nivel o cantidad está fuera de lo que admite ese modelo | Ajuste el valor para ese modelo según la API de imágenes |
| 400 "media_download_failed" | La URL de una imagen o video de referencia no es accesible públicamente | Use una URL HTTP(S) que se pueda descargar sin iniciar sesión |
| 404 "El grupo al que pertenece esta clave de API ha sido dado de baja y ya no atiende solicitudes…" | El grupo al que pertenece esta clave fue descontinuado | Cree una nueva clave en un grupo actualmente disponible en la consola y reemplace la anterior |
| "node / npm is not recognized" | Node.js no está instalado o no está en PATH | Reinstale desde nodejs.org (mantenga las 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 esta tabla? 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.