Códigos de error | OpenAI API

Esta guía ofrece una descripción general de los códigos de error que puedes encontrar tanto en la API como en nuestra biblioteca oficial de Python. Cada código de error mencionado en la descripción general tiene una sección dedicada con más orientación.

Errores de la API

Código	Descripción general
400 - Argumento `service_tier` no válido	Causa: el nivel de servicio solicitado o resultante no está permitido para el proyecto. Solución: establece `service_tier` en un nivel permitido para el proyecto o actualiza los niveles de servicio permitidos en la configuración del proyecto.
401 - Autenticación no válida	Causa: autenticación no válida Solución: asegúrate de usar la clave de API y la organización correctas para la solicitud.
401 - La clave de API proporcionada es incorrecta	Causa: la clave de API usada en la solicitud no es correcta. Solución: verifica que la clave de API utilizada sea correcta, borra la caché de tu navegador o genera una nueva.
401 - Debes pertenecer a una organización para usar la API	Causa: tu cuenta no pertenece a ninguna organización. Solución: contáctanos para que te agreguemos a una nueva organización o pídele al administrador de tu organización que te invite a una organización.
401 - IP no autorizada	Causa: la dirección IP de tu solicitud no está en la lista de direcciones IP permitidas configurada para tu proyecto u organización. Solución: envía la solicitud desde la IP correcta o actualiza la configuración de la lista de direcciones IP permitidas.
403 - País, región o territorio no admitido	Causa: estás accediendo a la API desde un país, una región o un territorio no admitido. Solución: consulta esta página para obtener más información.
429 - Saldo de créditos agotado	Código: `credit_balance_exhausted` Causa: tu organización no tiene créditos prepagados disponibles. Solución: agrega créditos para seguir usando la API.
429 - Se alcanzó el límite de solicitudes	Causa: estás enviando solicitudes con demasiada frecuencia. Solución: espacia tus solicitudes y respeta el encabezado `Retry-After` cuando esté presente. Lee la guía de límites de solicitudes.
429 - Reduce el ritmo	Tipo: `rate_limit_error` Código: `slow_down` Causa: la frecuencia de tus solicitudes aumentó demasiado rápido. Solución: respeta el encabezado `Retry-After` cuando esté presente, reduce la frecuencia de tus solicitudes y auméntala gradualmente.
429 - Se alcanzó el límite de gasto de la organización	Código: `organization_spend_limit_exceeded` Causa: tu organización alcanzó su límite de gasto de cumplimiento obligatorio. Solución: aumenta o elimina el límite de gasto de tu organización.
429 - Se alcanzó el límite de gasto del proyecto	Código: `project_spend_limit_exceeded` Causa: tu proyecto alcanzó su límite de gasto de cumplimiento obligatorio. Solución: aumenta o elimina el límite de gasto en la configuración de tu proyecto.
429 - Se alcanzó el límite de uso de la organización	Código: `organization_usage_limit_exceeded` Causa: tu organización alcanzó el límite de uso asignado por OpenAI. Solución: solicita un límite de uso aprobado más alto o contacta al equipo de soporte.
500 - El servidor tuvo un error al procesar tu solicitud	Causa: hay un problema en nuestros servidores. Solución: espera un momento y vuelve a intentar la solicitud. Contáctanos si el problema persiste. Consulta la página de estado.
503 - Modelo sobrecargado temporalmente	Tipo: `service_unavailable_error` Código: `server_is_overloaded` Causa: el modelo solicitado está sobrecargado temporalmente. Solución: respeta el encabezado `Retry-After` cuando esté presente y luego vuelve a intentar la solicitud.

Para los errores relacionados con la facturación, revisa error.code para identificar la causa específica. El campo más general error.type puede seguir siendo insufficient_quota.

Reintentar solicitudes con errores de facturación, gasto o cuota no restablecerá el acceso a la API. Actualiza los créditos o límites correspondientes antes de enviar otra solicitud.

Errores del modo WebSocket

Si usas el modo WebSocket de la API Responses, es posible que encuentres estos errores adicionales:

previous_response_not_found: no se puede resolver previous_response_id a partir del estado disponible. Vuelve a intentarlo con el contexto de entrada completo y previous_response_id establecido en null.
websocket_connection_limit_reached: la conexión alcanzó el límite de 60 minutos. Abre una nueva conexión WebSocket y continúa.

Tipos de errores de la biblioteca de Python

Python lanza RateLimitError para las respuestas 429 y InternalServerError para las respuestas 503. Si tu manejador antes capturaba solo una de estas clases para los casos de limitación de tráfico y sobrecarga, maneja ambas e inspecciona error.code. Por ejemplo, la sobrecarga de video ahora devuelve 503, mientras que antes devolvía 429. Consulta la guía de migración para conocer los cambios específicos de cada punto de acceso.

Tipo	Descripción general
APIConnectionError	Causa: problema al conectarse a nuestros servicios. Solución: revisa la configuración de red, la configuración del proxy, los certificados SSL o las reglas del firewall.
APITimeoutError	Causa: se agotó el tiempo de espera de la solicitud. Solución: espera un momento y vuelve a enviar la solicitud. Comunícate con nosotros si el problema persiste.
AuthenticationError	Causa: tu clave de API o token no era válido, había vencido o se había revocado. Solución: revisa tu clave de API o token y asegúrate de que sea correcto y esté activo. Es posible que debas generar uno nuevo desde el panel de tu cuenta.
BadRequestError	Causa: tu solicitud tenía un formato incorrecto o le faltaban algunos parámetros obligatorios, como un token o una entrada. Solución: el mensaje de error debería indicar el error específico que se cometió. Consulta la documentación del método específico de la API al que estás llamando y asegúrate de enviar parámetros válidos y completos. Es posible que también debas revisar la codificación, el formato o el tamaño de los datos de tu solicitud.
ConflictError	Causa: otra solicitud actualizó el recurso. Solución: intenta actualizar el recurso de nuevo y asegúrate de que ninguna otra solicitud esté intentando actualizarlo.
InternalServerError	Causa: problema de nuestro lado. Solución: espera un momento y vuelve a enviar la solicitud. Comunícate con nosotros si el problema persiste.
NotFoundError	Causa: el recurso solicitado no existe. Solución: asegúrate de usar el identificador de recurso correcto.
PermissionDeniedError	Causa: no tienes acceso al recurso solicitado. Solución: asegúrate de usar la clave de API, el ID de organización y el ID de recurso correctos.
RateLimitError	Causa: alcanzaste el límite de solicitudes asignado o aumentaste el tráfico demasiado rápido. Solución: regula la frecuencia de tus solicitudes y respeta `Retry-After` cuando esté presente, sin exceder tus límites de reintentos. Encontrarás más información en nuestra guía de límites de solicitudes.
UnprocessableEntityError	Causa: no se puede procesar la solicitud aunque el formato sea correcto. Solución: vuelve a intentar la solicitud.

Errores persistentes

Si el problema persiste, contacta a nuestro equipo de soporte por chat y proporciónale la siguiente información:

El modelo que estabas usando
El mensaje y el código de error que recibiste
Los datos y encabezados de la solicitud que enviaste
La marca de tiempo y la zona horaria de tu solicitud
Cualquier otro detalle relevante que pueda ayudarnos a diagnosticar el problema

Nuestro equipo de soporte investigará el problema y te responderá lo antes posible. Ten en cuenta que los tiempos de espera para recibir soporte pueden ser prolongados debido a la alta demanda. También puedes publicar en nuestro foro de la comunidad, pero asegúrate de omitir cualquier información confidencial.

Manejo de errores

Te recomendamos manejar mediante código los errores que devuelve la API. Para hacerlo, puedes usar un fragmento de código como el siguiente:

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra",
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("Failed to connect to the OpenAI API:", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("OpenAI API request exceeded its rate limit:", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API returned an error:", error.status, error.message);
  } else {
    throw error;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.responses.create(model="gpt-6-astra", input="Hello world")
except openai.APIConnectionError as e:
    print(f"Failed to connect to OpenAI API: {e}")
except openai.RateLimitError as e:
    print(f"OpenAI API request exceeded rate limit: {e}")
except openai.APIError as e:
    print(f"OpenAI API returned an API Error: {e}")
else:
    print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Hello world")},
	})
	if err != nil {
		var apiError *openai.Error
		if errors.As(err, &apiError) {
			fmt.Println("OpenAI API returned an API error:", apiError)
			return
		}
		fmt.Println("Failed to connect to OpenAI API:", err)
		return
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.errors.OpenAIServiceException;
import com.openai.models.responses.ResponseCreateParams;

try {
  var response =
      client
          .responses()
          .create(
              ResponseCreateParams.builder().model("gpt-6-astra").input("Say hello.").build());

  response.output().stream()
      .flatMap(item -> item.message().stream())
      .flatMap(message -> message.content().stream())
      .flatMap(content -> content.outputText().stream())
      .forEach(text -> System.out.println(text.text()));
} catch (OpenAIServiceException error) {
  System.err.println(error.getMessage());
}

1
2
3
4
5
6
7
8
9require "openai"

client = OpenAI::Client.new
begin
  response = client.responses.create(model: "gpt-6-astra", input: "Say hello.")
  puts(response.output_text)
rescue OpenAI::Errors::APIError => error
  warn(error.message)
end

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Recursos

API heredadas

Elige un modelo

Texto y código

Diseño de prompts

Razonamiento

Imágenes y video

Tiempo real y audio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Búsqueda y recuperación

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Contenido multimedia

GPT-Live

Realtime API

Desarrollar con voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos fundamentales

Plan

Build

Test and publish

Conversion specs

Guías

Recursos

Primeros pasos

Guías

File Upload

API

Measurement

Advertiser API

Referencia de la API

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las capacidades de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Extender y automatizar

Entornos

Crear con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Seguridad cibernética

Primeros pasos

ChatGPT Work

Identidad y autenticación

Acceso, políticas y modelos del espacio de trabajo

Controles de complementos y conectores

Uso, gobernanza y cumplimiento

Implementación y proveedores de modelos

Comunidad

Blog

Comunidad

Blog