Códigos de erro | OpenAI API

Este guia apresenta uma visão geral dos códigos de erro que você pode encontrar tanto na API quanto na nossa biblioteca oficial para Python. Cada código de erro mencionado na visão geral tem uma seção dedicada com mais orientações.

Erros da API

Código	Visão geral
400 - Argumento `service_tier` inválido	Causa: O nível de serviço solicitado ou determinado não é permitido para o projeto. 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: Autenticação inválida Solução: Verifique se a chave de API e a organização usadas na requisição estão corretas.
401 - Chave de API incorreta fornecida	Causa: A chave de API usada na requisição está incorreta. Solução: Verifique se a chave de API usada está correta, limpe o cache do navegador ou gere uma nova chave.
401 - Você precisa ser membro 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 ser adicionado a 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 da sua requisição não consta na lista de IPs permitidos configurada para seu projeto ou organização. Solução: Envie a requisiçã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 a partir de um país, região ou território sem suporte. Solução: Consulte esta página para obter mais informações.
429 - Saldo de créditos esgotado	Código: `credit_balance_exhausted` Causa: Sua organização não tem mais créditos pré-pagos. Solução: Adicione créditos para continuar usando a API.
429 - Limite de taxa de requisições atingido	Causa: Você está enviando requisições com muita frequência. Solução: Espace suas requisições e respeite o cabeçalho `Retry-After` quando ele estiver presente. Leia o guia de limites de taxa.
429 - Reduza o ritmo	Tipo: `rate_limit_error` Código: `slow_down` Causa: Sua taxa de requisições aumentou rápido demais. Solução: Respeite o cabeçalho `Retry-After` quando ele estiver presente, reduza sua taxa de requisições e aumente-a gradualmente.
429 - Limite de gastos da organização atingido	Código: `organization_spend_limit_exceeded` Causa: Sua organização atingiu o limite de gastos imposto. Solução: Aumente ou remova o limite de gastos da sua organização.
429 - Limite de gastos do projeto atingido	Código: `project_spend_limit_exceeded` Causa: Seu projeto atingiu o limite de gastos imposto. 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 atribuído pela OpenAI. Solução: Solicite um limite de uso aprovado maior ou entre em contato com o suporte.
500 - O servidor encontrou um erro ao processar sua requisição	Causa: Problema nos nossos servidores. Solução: Aguarde um pouco e tente enviar sua requisição novamente. Entre em contato conosco se o problema persistir. 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 cabeçalho `Retry-After` quando ele estiver presente e, em seguida, tente enviar sua requisição novamente.

Para erros relacionados ao faturamento, verifique error.code para identificar a causa específica. O campo mais abrangente error.type ainda pode ser insufficient_quota.

Repetir requisições após erros de faturamento, gastos ou cota não restabelecerá o acesso à API. Atualize os créditos ou limites correspondentes antes de enviar outra requisição.

Erros do modo WebSocket

Se você estiver usando o modo WebSocket da Responses API, poderá encontrar estes erros adicionais:

previous_response_not_found: Não é possível resolver previous_response_id a partir do estado disponível. Tente novamente com o contexto de entrada completo e 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 e continue.

Tipos de erro da biblioteca Python

Python lança RateLimitError para respostas 429 e InternalServerError para respostas 503. Se seu código de tratamento de erros antes capturava apenas uma dessas classes para limitação de taxa e sobrecarga, trate ambas e inspecione error.code. A sobrecarga de vídeo, por exemplo, agora retorna 503, enquanto antes retornava 429. Consulte as orientações de migração para conhecer as mudanças específicas de cada endpoint.

Tipo	Visão geral
APIConnectionError	Causa: Problema ao se conectar aos nossos serviços. Solução: Verifique as configurações de rede, a configuração do proxy, os certificados SSL ou as regras de firewall.
APITimeoutError	Causa: O tempo limite da requisição foi excedido. Solução: Aguarde um pouco e tente enviar a requisição novamente. Entre em contato conosco se o problema persistir.
AuthenticationError	Causa: Sua chave de API ou seu token era inválido, havia expirado ou havia sido revogado. Solução: Verifique sua chave de API ou seu token e confirme se está correto e ativo. Talvez seja necessário gerar uma nova chave ou um novo token no painel da sua conta.
BadRequestError	Causa: Sua requisição estava malformada ou faltavam alguns 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 está enviando parâmetros válidos e completos. Talvez também seja necessário verificar a codificação, o formato ou o tamanho dos dados da requisição.
ConflictError	Causa: O recurso foi atualizado por outra requisição. Solução: Tente atualizar o recurso novamente e verifique se nenhuma outra requisição está tentando atualizá-lo.
InternalServerError	Causa: Problema do nosso lado. Solução: Aguarde um pouco e tente enviar a requisição novamente. Entre em contato conosco se o problema persistir.
NotFoundError	Causa: O recurso solicitado não existe. Solução: Verifique se você está usando o identificador de recurso correto.
PermissionDeniedError	Causa: Você não tem acesso ao recurso solicitado. Solução: Verifique se você está usando a chave de API, o ID da organização e o ID do recurso corretos.
RateLimitError	Causa: Você atingiu o limite de taxa atribuído a você ou aumentou o tráfego rápido demais. Solução: Controle o ritmo das requisições e respeite `Retry-After` quando estiver presente, observando seus limites de novas tentativas. Saiba mais no nosso guia de limites de taxa.
UnprocessableEntityError	Causa: Não foi possível processar a requisição, apesar de o formato estar correto. Solução: Tente enviar a requisiçã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 que você recebeu
Os dados e os cabeçalhos da requisição que você enviou
A data, a hora e o fuso horário da sua requisição
Quaisquer outros detalhes relevantes que possam nos ajudar a diagnosticar o problema

Nossa equipe de suporte investigará o problema e responderá assim que possível. O tempo de espera na fila de suporte pode ser longo devido à alta demanda. Você também pode publicar no nosso Fórum da Comunidade, mas lembre-se de omitir qualquer informação sensível.

Tratamento de erros

Recomendamos tratar no seu código os erros retornados pela API. Para isso, você pode usar um trecho de código como o 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

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog