Plataforma

Erros

Os erros são devolvidos em JSON no formato do endpoint chamado, com uma mensagem para as pessoas e, nos endpoints ao estilo da OpenAI, um código estável para os programas.

A estrutura

Endpoints ao estilo da 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 são devolvidos no formato da Anthropic, que não tem código: use o estado HTTP e error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Todas as respostas de chat, imagem e vídeo, com ou sem erro, têm um cabeçalho x-request-id.

Códigos

EstadoCódigoO que fazer
400invalid_requestCorrija o pedido: message indica o problema e param indica onde está.
400unsupported_contentO modelo não lê esse tipo de ficheiro. Remova-o ou escolha um modelo que o leia.
400invalid_urlNão foi possível descarregar um dos links do pedido. A mensagem indica o estado recebido na resposta.
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 indica que a conversa é demasiado longa. Encurte-a ou escolha um modelo com um contexto maior.
400max_tokens_reachedUma resposta de /v1/messages sem streaming atingiu o seu max_tokens a meio de uma chamada de ferramenta, pelo que a mensagem está incompleta. O conteúdo gerado é cobrado. Volte a enviar o pedido com um max_tokens mais alto.
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 montante reservado pelos pedidos em curso, não cobre este pedido, ou esgotou-se a meio de uma resposta. Adicione crédito em Faturação ou peça uma resposta mais curta com um max_tokens mais baixo. Quando o carregamento automático já tiver iniciado um reforço de saldo, a mensagem indica-o: tente novamente após alguns segundos.
402key_budget_exceededO pedido pode ultrapassar o orçamento mensal da chave, contando com os pedidos em curso, ou atingiu-o a meio. Aumente o orçamento ou aguarde pelo próximo mês.
402key_daily_budget_exceededO mesmo para o orçamento diário da chave. Aumente-o ou aguarde pela 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_foundVerifique o ID do modelo na página de modelos.
404unknown_urlEste endpoint não existe. Verifique o caminho e o URL base.
404video_not_foundNão existe nenhum vídeo com esse ID neste espaço de trabalho.
404image_not_foundNão existe nenhum pedido de imagem com esse ID neste espaço de trabalho (GET /v1/images/{id}, para pedidos feitos com um callback_url).
409video_not_readyO vídeo ainda não está concluído: consulte o estado periodicamente até ser completed.
409video_failedA criação do vídeo falhou, por isso não há nada para descarregar. O erro indica o motivo.
410video_expiredO vídeo foi eliminado, através da Biblioteca ou após os seus 30 dias.
413too_largeO pedido ou um ficheiro excede o limite. Envie ficheiros 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 pedidos em curso ao mesmo tempo. Tente novamente após o número de segundos indicado em retry-after, quando um deles terminar.
500server_errorOcorreu um erro do nosso lado. Tente novamente.
502stream_interruptedEnviado como último evento de um stream interrompido. O conteúdo transmitido antes da interrupção é cobrado, mas nada depois; tente novamente.
503model_unavailableO modelo está indisponível neste momento. Tente novamente após o número de segundos indicado em retry-after ou ative o encaminhamento inteligente. Sem retry-after e com x-should-retry: false, o modelo está disponível, mas devolve sempre uma mensagem de erro para este pedido: não o reenvie sem alterações.
503server_restartingA Zurelay está a reiniciar a máquina que recebeu o seu pedido. Tente novamente de imediato: outra máquina trata do pedido. Sem cobrança, exceto se já tiver começado um stream: nesse caso, o conteúdo que recebeu é cobrado, tal como num stream interrompido.
503storage_unavailableFoi gerada uma imagem, mas não foi possível entregá-la. Sem cobrança; tente novamente.
503service_unavailableUm problema passageiro do nosso lado. Tente novamente.

Novas tentativas

  • Repita os pedidos com 429 e 503, aguardando o número de segundos indicado no cabeçalho retry-after (ou aumentando exponencialmente o intervalo entre tentativas), exceto se a resposta indicar x-should-retry: false.
  • Não repita pedidos com outros erros 4xx sem os alterar: voltarão a falhar da mesma forma.
  • Os pedidos que falham são gratuitos, pelo que repetir não custa nada até um ter sucesso. Um stream interrompido a meio é cobrado pelo conteúdo entregue, e o raro 503 com x-should-retry: false é cobrado pela entrada (ver Faturação).
  • Os SDKs oficiais da OpenAI e da Anthropic já repetem automaticamente os pedidos com os erros adequados.

Erros a meio do stream

Os erros que um modelo devolve sobre o próprio pedido (um parâmetro que não aceita, um prompt demasiado longo) chegam com a mensagem e o código do próprio modelo, como 400 ou 422.

Erros a meio do stream

Depois de um stream começar, uma falha já não pode ser comunicada por um código de estado HTTP. Em vez disso, recebe um evento final de erro (no formato do endpoint) e o stream termina. São cobradas a entrada e a saída que recebeu antes desse evento, mas nada depois. Isto é raro: a maioria dos problemas é detetada e os pedidos são repetidos antes do primeiro token.

O mesmo tipo de evento termina um stream quando o saldo ou o orçamento da chave se esgota a meio, com insufficient_quota, key_budget_exceeded ou key_daily_budget_exceeded. Um pedido sem streaming que esgote o saldo ou o orçamento a meio devolve o que foi escrito, truncado 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 que indica o código.

Tem dúvidas ou falta alguma coisa? Contacte a nossa equipa de apoio e responderemos por email, normalmente num minuto.