Códigos de error | OpenAI API

Esta guía resume los códigos de error que puedes encontrar al usar la API o nuestra biblioteca oficial de Python. Cada código de error que se menciona en el resumen tiene una sección con más detalles sobre cómo resolverlo.

Errores de la API

Código	Resumen
400 - Argumento `service_tier` no válido	Causa: el proyecto no permite el nivel de servicio que solicitaste o el que determinó la API. Solución: asigna a `service_tier` 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: la autenticación no es válida. Solución: verifica que la clave de API y la organización que realiza la solicitud sean las correctas.
401 - La clave de API proporcionada es incorrecta	Causa: la clave de API de la solicitud es incorrecta. Solución: verifica que estés usando la clave de API correcta, borra la caché del navegador o genera una clave 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 organización nueva o pide a quien administra tu organización que te invite a una organización.
401 - Dirección IP no autorizada	Causa: la dirección IP desde la que enviaste la solicitud no está en la lista de direcciones IP permitidas de tu proyecto u organización. Solución: envía la solicitud desde la dirección 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 donde no está disponible. Solución: consulta esta página para obtener más información.
429 - Se agotó el saldo de créditos	Código: `credit_balance_exhausted` Causa: a tu organización no le quedan créditos prepagados. 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 las solicitudes y respeta el tiempo indicado en el encabezado `Retry-After` cuando esté presente. Consulta la guía sobre límites de solicitudes.
429 - Reduce la frecuencia de las solicitudes	Tipo: `rate_limit_error` Código: `slow_down` Causa: la frecuencia de tus solicitudes aumentó demasiado rápido. Solución: respeta el tiempo indicado en 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ó el límite de gasto que tiene establecido. Solución: aumenta o elimina el límite de gasto de la organización.
429 - Se alcanzó el límite de gasto del proyecto	Código: `project_spend_limit_exceeded` Causa: tu proyecto alcanzó el límite de gasto que tiene establecido. Solución: aumenta o elimina el límite de gasto en la configuración del 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 que le asignó OpenAI. Solución: solicita que se aumente el límite de uso aprobado o contacta al equipo de soporte.
500 - El servidor encontró un error al procesar tu solicitud	Causa: hay un problema en nuestros servidores. Solución: espera un momento y vuelve a enviar la solicitud. Contáctanos si el problema persiste. Consulta la página de estado.
503 - El modelo está sobrecargado temporalmente	Tipo: `service_unavailable_error` Código: `server_is_overloaded` Causa: el modelo solicitado está sobrecargado temporalmente. Solución: si está presente el encabezado `Retry-After`, espera el tiempo que indica y vuelve a enviar la solicitud.

Si el error está relacionado con la facturación, revisa error.code para identificar la causa específica. El campo más general error.type puede seguir teniendo el valor insufficient_quota.

Si el error es de facturación, gasto o cuota, volver a enviar la solicitud no restablecerá el acceso a la API. Actualiza los créditos o los límites correspondientes antes de enviar otra solicitud.

Errores del modo WebSocket

Si usas el modo WebSocket de la API de Respuestas, también puedes encontrar estos errores:

previous_response_not_found: la API no puede resolver previous_response_id con la información de estado disponible. Vuelve a enviar la solicitud con todo el contexto de entrada y con previous_response_id establecido en null.
websocket_connection_limit_reached: la conexión alcanzó el límite de 60 minutos. Abre una conexión WebSocket nueva y continúa.

Tipos de errores de la biblioteca de Python

Python lanza RateLimitError para las respuestas 429 e InternalServerError para las respuestas 503. Si tu código solo capturaba una de estas clases para gestionar tanto las restricciones de tráfico como las sobrecargas, captura ambas y revisa error.code. Por ejemplo, en caso de sobrecarga de video, ahora se devuelve 503 donde antes se devolvía 429. Consulta la guía de migración para conocer los cambios en cada punto de acceso.

Tipo	Resumen
APIConnectionError	Causa: hubo un problema al conectarse a nuestros servicios. Solución: revisa la configuración de red y 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. Contáctanos 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: verifica que estés usando la clave de API o el token correcto y que siga vigente. Es posible que debas generar uno nuevo desde el panel de tu cuenta.
BadRequestError	Causa: la solicitud tenía un formato incorrecto o le faltaban parámetros obligatorios, como un token o una entrada. Solución: el mensaje de error debería indicar qué falló. Consulta la documentación del método de la API al que llamas y verifica que los parámetros que envías sean válidos y estén completos. También es posible que debas revisar la codificación, el formato o el tamaño de los datos de la solicitud.
ConflictError	Causa: otra solicitud actualizó el recurso. Solución: intenta actualizar el recurso de nuevo y verifica que ninguna otra solicitud esté intentando actualizarlo.
InternalServerError	Causa: hubo un problema en nuestros sistemas. Solución: espera un momento y vuelve a enviar la solicitud. Contáctanos si el problema persiste.
NotFoundError	Causa: el recurso solicitado no existe. Solución: verifica que estés usando el identificador de recurso correcto.
PermissionDeniedError	Causa: no tienes acceso al recurso solicitado. Solución: verifica que la clave de API, el ID de la organización y el ID del recurso sean los correctos.
RateLimitError	Causa: alcanzaste el límite de solicitudes que tienes asignado o aumentaste el tráfico demasiado rápido. Solución: espacia tus solicitudes y respeta el tiempo indicado en `Retry-After` cuando esté presente, sin superar el límite de reintentos. Consulta nuestra guía sobre límites de solicitudes para obtener más información.
UnprocessableEntityError	Causa: no se pudo procesar la solicitud aunque el formato era correcto. Solución: vuelve a enviar la solicitud.

Errores persistentes

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

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

Nuestro equipo de soporte investigará el problema y te responderá lo antes posible. Si hay mucha demanda, el tiempo de espera puede ser prolongado. También puedes publicar en nuestro foro de la comunidad. Asegúrate de omitir toda información sensible.

Manejo de errores

Te recomendamos manejar en tu 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

Proveedores de servicios en la nube

Recursos

API heredadas

Elige un modelo

Texto y código

Redacción de prompts

Razonamiento

Imágenes

Tiempo real y audio

Modelos especializados

API de agentes

Agents SDK

ChatKit

Búsqueda y recuperación de información

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Multimedia

GPT-Live

Realtime API

Desarrollar aplicaciones de voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Evaluación

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos básicos

Planificación

Desarrollo

Pruebas y publicación

Especificaciones de conversión

Guías

Recursos

Identidad

Uso del plan de ChatGPT

Guías

Carga de archivos

API

Medición

API para anunciantes

Referencia de la API

Primeros pasos

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Sites

dots

ChatGPT Espacio

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las funciones de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Ampliar funciones y automatizar

Entornos

Codex Cloud

Desarrollar con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Ciberseguridad

Primeros pasos

Configuración de funciones

Identidad y acceso