Códigos de erro | OpenAI API

Este guia apresenta os códigos de erro que você pode encontrar ao usar a API ou nossa biblioteca oficial para Python. Cada código de erro mencionado na visão geral tem uma seção com orientações mais detalhadas.

Erros da API

Código	Visão geral
400 - Argumento `service_tier` inválido	Causa: O projeto não permite o nível de serviço solicitado ou determinado pela API. Solução: Defina `service_tier` como um nível permitido para o projeto ou atualize os níveis de serviço permitidos nas configurações do projeto.
401 - Autenticação inválida	Causa: As credenciais de autenticação são inválidas. Solução: Verifique se a solicitação usa a chave de API correta e se a organização que faz a solicitação também está correta.
401 - Chave de API incorreta	Causa: A chave de API usada na solicitação está incorreta. Solução: Verifique se a chave de API está correta, limpe o cache do navegador ou gere uma nova chave.
401 - Você precisa fazer parte de uma organização para usar a API	Causa: Sua conta não faz parte de uma organização. Solução: Entre em contato conosco para ingressar em uma nova organização ou peça ao administrador da sua organização que convide você para uma organização.
401 - IP não autorizado	Causa: O IP de origem da solicitação não consta na lista de IPs permitidos do projeto ou da organização. Solução: Envie a solicitação a partir do IP correto ou atualize as configurações da lista de IPs permitidos.
403 - País, região ou território sem suporte	Causa: Você está acessando a API de um país, região ou território sem suporte. Solução: Consulte a página de países com suporte para saber mais.
429 - Saldo de créditos esgotado	Código: `credit_balance_exhausted` Causa: Os créditos pré-pagos da sua organização acabaram. Solução: Adicione créditos para continuar usando a API.
429 - Limite de taxa de solicitações atingido	Causa: Você está enviando solicitações com muita frequência. Solução: Espace as solicitações e respeite o intervalo indicado no cabeçalho `Retry-After`, se estiver presente. Consulte o guia de limites de taxa.
429 - Reduza a taxa de solicitações	Tipo: `rate_limit_error` Código: `slow_down` Causa: Sua taxa de solicitações aumentou rápido demais. Solução: Respeite o intervalo indicado no cabeçalho `Retry-After`, se estiver presente. Reduza a taxa de solicitações e volte a aumentá-la gradualmente.
429 - Limite de gastos da organização atingido	Código: `organization_spend_limit_exceeded` Causa: Sua organização atingiu o limite de gastos em vigor. Solução: Aumente ou remova o limite de gastos da organização.
429 - Limite de gastos do projeto atingido	Código: `project_spend_limit_exceeded` Causa: Seu projeto atingiu o limite de gastos em vigor. Solução: Aumente ou remova o limite de gastos nas configurações do projeto.
429 - Limite de uso da organização atingido	Código: `organization_usage_limit_exceeded` Causa: Sua organização atingiu o limite de uso definido pela OpenAI. Solução: Solicite o aumento do limite de uso aprovado ou entre em contato com o suporte.
500 - Erro no servidor ao processar a solicitação	Causa: Ocorreu um problema nos nossos servidores. Solução: Aguarde um pouco e tente novamente. Se o problema persistir, entre em contato conosco. Consulte a página de status.
503 - Modelo temporariamente sobrecarregado	Tipo: `service_unavailable_error` Código: `server_is_overloaded` Causa: O modelo solicitado está temporariamente sobrecarregado. Solução: Respeite o intervalo indicado no cabeçalho `Retry-After`, se estiver presente, e tente novamente.

Para erros relacionados à cobrança, verifique error.code para identificar a causa específica. O campo mais geral error.type ainda pode ter o valor insufficient_quota.

Em caso de erro de cobrança, limite de gastos ou cota, repetir a solicitação não restabelece o acesso à API. Adicione créditos ou ajuste o limite correspondente antes de enviar outra solicitação.

Erros do modo WebSocket

Ao usar o modo WebSocket da API Responses, você também pode encontrar os seguintes erros:

previous_response_not_found: Não foi possível localizar a resposta indicada por previous_response_id com base no estado disponível. Tente novamente com o contexto de entrada completo e com previous_response_id definido como null.
websocket_connection_limit_reached: A conexão atingiu o limite de 60 minutos. Abra uma nova conexão WebSocket para continuar.

Tipos de erro da biblioteca Python

A biblioteca Python lança RateLimitError para respostas 429 e InternalServerError para respostas 503. Se o seu código capturava apenas uma dessas classes para tratar limitação de tráfego e sobrecarga, passe a tratar as duas e verifique error.code. Por exemplo, uma sobrecarga no processamento de vídeo agora retorna 503, enquanto antes retornava 429. Consulte as orientações de migração para ver o que mudou em cada endpoint.

Tipo	Visão geral
APIConnectionError	Causa: Houve um problema de conexão com nossos serviços. Solução: Verifique as configurações de rede, a configuração do proxy, os certificados SSL ou as regras do firewall.
APITimeoutError	Causa: O tempo de espera da solicitação se esgotou. Solução: Aguarde um pouco e tente novamente. Se o problema persistir, entre em contato conosco.
AuthenticationError	Causa: A chave de API ou o token é inválido, expirou ou foi revogado. Solução: Verifique se a chave de API ou o token está correto e ativo. Talvez seja necessário gerar outra chave ou outro token no painel da conta.
BadRequestError	Causa: A solicitação está malformada ou faltam parâmetros obrigatórios, como um token ou uma entrada. Solução: A mensagem de erro deve indicar o problema específico. Consulte a documentação do método da API que você está chamando e verifique se os parâmetros enviados são válidos e estão completos. Talvez também seja necessário verificar a codificação, o formato ou o tamanho dos dados da solicitação.
ConflictError	Causa: Outra solicitação atualizou o recurso. Solução: Tente atualizar o recurso novamente e verifique se nenhuma outra solicitação está tentando atualizá-lo.
InternalServerError	Causa: Ocorreu um problema nos nossos sistemas. Solução: Aguarde um pouco e tente novamente. Se o problema persistir, entre em contato conosco.
NotFoundError	Causa: O recurso solicitado não existe. Solução: Verifique se você está usando o identificador correto do recurso.
PermissionDeniedError	Causa: Você não tem acesso ao recurso solicitado. Solução: Verifique se a chave de API, o ID da organização e o ID do recurso estão corretos.
RateLimitError	Causa: Você atingiu o limite de taxa definido para o seu uso ou aumentou o tráfego rápido demais. Solução: Espace as solicitações e respeite o intervalo indicado por `Retry-After`, quando presente, sem exceder o limite de novas tentativas. Saiba mais no guia de limites de taxa.
UnprocessableEntityError	Causa: Não foi possível processar a solicitação, embora o formato esteja correto. Solução: Envie a solicitação novamente.

Erros persistentes

Se o problema persistir, entre em contato com nossa equipe de suporte pelo chat e forneça as seguintes informações:

O modelo que você estava usando
A mensagem e o código de erro recebidos
Os dados e cabeçalhos enviados na solicitação
A data, a hora e o fuso horário da solicitação
Outros detalhes relevantes que possam ajudar no diagnóstico do problema

Nossa equipe de suporte investigará o problema e responderá assim que possível. Em períodos de alta demanda, o tempo de espera pelo atendimento pode ser longo. Você também pode publicar no fórum da comunidade, tomando o cuidado de omitir informações confidenciais.

Tratamento de erros

Recomendamos tratar no código os erros retornados pela API. Para isso, você pode usar um trecho de código como o do exemplo abaixo:

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

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso