Erros

Uma só forma para todas as falhas.

Quando algo falha, o estado HTTP não é 2xx e o corpo contém apenas um objeto error:

json

{
  "error": {
    "message": "Insufficient credits: this request needs 60 credits. Top up and try again.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  }
}

Campos

Campo	Descrição
message	Feito para ser lido, em inglês. Não uses como condição: a redação muda
type	Categoria geral, ver abaixo
code	Motivo concreto. É neste campo que deves ramificar
param	Nome do parâmetro em causa, ou null quando não é atribuível

Códigos frequentes

HTTP	code	Significado
401	missing_api_key	Sem cabeçalho Authorization ou fora do formato Bearer sk-xxx
401	invalid_api_key	Chave desconhecida, desativada ou eliminada — deliberadamente indistinguíveis
400	invalid_request	Problema de parâmetros; lê message. prompt vazio, modo imagem sem imagem, etc.
402	insufficient_credits	Sem créditos. Carrega e consulta /v1/credits antes de repetir
429	rate_limit_exceeded	Chamadas a mais. Recua e tenta de novo
429	concurrency_limit_reached	Limite de concorrência ou quota diária atingidos. Tenta mais tarde
404	not_found	A tarefa não existe ou não pertence a esta conta
502	generation_failed	Numa chamada síncrona falharam todas as imagens. Os créditos já foram devolvidos
504	generation_timeout	Esgotou-se a espera de uma chamada síncrona. A tarefa continua e os créditos não são devolvidos: vai buscá-la a /v1/tasks/{id} com o id da mensagem
500	internal_error	Falha do servidor. Pode repetir-se; se persistir, contacta-nos

Um trabalho assíncrono que falha depois de aceite não usa esta forma: a chamada devolve 200, o objeto de tarefa traz status failed e o motivo fica em error. Só as chamadas síncronas de imagem transformam a falha num 502.