Plataforma

Erros

Os erros retornam em JSON no formato do endpoint que você chamou, com uma mensagem para pessoas e, nos endpoints no padrão OpenAI, um código estável para programas.

O formato

Endpoints no padrão OpenAI
{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

Em /v1/messages, os mesmos erros vêm no formato da Anthropic, que não tem código: use o status HTTP e error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Toda resposta de chat, imagem e vídeo, com erro ou não, tem um cabeçalho x-request-id.

Códigos

StatusCódigoO que fazer
400invalid_requestCorrija a requisição: a mensagem diz o que está errado e param indica onde.
400unsupported_contentO modelo não lê esse tipo de arquivo. Remova-o ou escolha um modelo que leia.
400invalid_urlNão foi possível baixar um link da requisição. A mensagem informa o status retornado.
400invalid_imageNão foi possível usar uma imagem de entrada (tipo, tamanho ou link).
400image_not_generatedO modelo recusou o prompt. Sem cobrança.
400context_length_exceededO modelo informa que a conversa é longa demais para ele. Encurte-a ou escolha um modelo com contexto maior.
400max_tokens_reachedUma resposta de /v1/messages sem streaming atingiu seu max_tokens no meio de uma chamada de ferramenta, então a mensagem está incompleta. O que foi gerado é cobrado. Envie novamente com um max_tokens maior.
401missing_api_keyEnvie a chave em Authorization ou x-api-key.
401invalid_api_keyA chave está incorreta ou foi revogada.
401expired_api_keyCrie uma nova chave.
402insufficient_quotaO saldo, descontando o valor reservado pelas requisições em andamento, não cobre esta requisição, ou acabou durante uma resposta. Adicione créditos em Faturamento ou peça uma resposta menor reduzindo max_tokens. Quando a recarga automática já iniciou uma recarga, a mensagem informa isso: tente novamente após alguns segundos.
402key_budget_exceededA requisição pode fazer a chave ultrapassar o orçamento mensal, contando as requisições em andamento, ou atingiu esse limite durante a execução. Aumente o orçamento ou espere o próximo mês.
402key_daily_budget_exceededO mesmo vale para o orçamento diário da chave. Aumente-o ou espere até meia-noite UTC.
403model_not_allowedA chave não tem permissão para usar este modelo.
403ip_not_allowedA chave só funciona a partir de outros endereços.
404model_not_foundConfira o ID do modelo na página de modelos.
404unknown_urlEsse endpoint não existe. Confira o caminho e a URL base.
404video_not_foundNão há vídeo com esse ID neste espaço de trabalho.
404image_not_foundNão há requisição de imagem com esse ID neste espaço de trabalho (GET /v1/images/{id}, para requisições feitas com callback_url).
409video_not_readyO vídeo ainda não está pronto: consulte-o periodicamente até o status ser completed.
409video_failedA geração do vídeo falhou, então não há nada para baixar. O erro informa o motivo.
410video_expiredO vídeo foi excluído, pela Biblioteca ou após seus 30 dias.
413too_largeA requisição ou um arquivo excede o limite. Envie arquivos grandes como links.
429rate_limit_exceededAguarde o número de segundos indicado em retry-after e tente novamente.
429concurrency_limit_exceededO espaço de trabalho já tem 32 requisições em execução simultânea. Tente novamente após o número de segundos indicado em retry-after, quando uma delas tiver terminado.
500server_errorAlgo deu errado do nosso lado. Tente novamente.
502stream_interruptedEnviado como o último evento de um stream interrompido. O conteúdo transmitido antes da interrupção é cobrado, mas nada depois dela; tente novamente.
503model_unavailableO modelo está indisponível no momento. Tente novamente após o número de segundos indicado em retry-after ou ative o roteamento inteligente. Sem retry-after e com x-should-retry: false, o modelo está disponível, mas retorna um erro para esta requisição todas as vezes: não a reenvie sem alterações.
503server_restartingA Zurelay está reiniciando a máquina que processava sua requisição. Tente novamente agora: outra máquina vai processá-la. Sem cobrança, a menos que um stream já tenha começado: nesse caso, o que chegou até você é cobrado, como em um stream interrompido.
503storage_unavailableUma imagem foi gerada, mas não pôde ser entregue. Sem cobrança; tente novamente.
503service_unavailableUm problema temporário do nosso lado. Tente novamente.

Novas tentativas

  • Tente novamente em caso de 429 e 503, aguardando os segundos indicados no cabeçalho retry-after (ou aumentando o intervalo exponencialmente), a menos que a resposta indique x-should-retry: false.
  • Não repita requisições com outros erros 4xx sem alterações: elas vão falhar do mesmo jeito.
  • Requisições que falham são gratuitas, então novas tentativas não custam nada até que uma dê certo. Um stream interrompido é cobrado pelo que entregou, e o raro 503 com x-should-retry: false é cobrado pela entrada (veja Faturamento).
  • Os SDKs oficiais da OpenAI e da Anthropic já fazem novas tentativas nos erros certos para você.

Erros durante o streaming

Erros que o modelo retorna sobre a própria requisição (um parâmetro que ele não aceita, um prompt longo demais) chegam com a mensagem e o código do próprio modelo, como 400 ou 422.

Erros durante o streaming

Depois que um stream começa, uma falha não pode mais ser retornada como status HTTP. Em vez disso, você recebe um evento final de erro (no formato do endpoint) e o stream termina. São cobradas a entrada e a saída que chegou até você antes disso, mas nada depois. Isso é raro: a maioria dos problemas é detectada e novas tentativas são feitas antes do primeiro token.

O mesmo tipo de evento encerra um stream quando o saldo ou o orçamento da chave acaba durante a execução, com insufficient_quota, key_budget_exceeded ou key_daily_budget_exceeded. Uma requisição sem streaming que fica sem saldo ou orçamento durante a execução retorna o que foi escrito, interrompido como uma resposta que atingiu max_tokens (finish_reason: "length", ou stop_reason: "max_tokens" em /v1/messages), com um cabeçalho x-zurelay-stopped indicando o código.

Tem dúvidas ou falta algo? Fale com nossa equipe de suporte e responderemos por e-mail, geralmente em até um minuto.