Erros

Todo erro, em todo endpoint, usa o mesmo envelope:

{
  "error": {
    "message": "Sua chave de API da Bayle está ausente ou não pôde ser verificada.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Os quatro campos estão sempre presentes. param e code podem ser nulos.

Campo	Significado
message	Legível por humanos, e localizado. Veja Idioma da resposta.
type	O vocabulário de error type da OpenAI, então o mapeamento de exceções de um SDK continua funcionando.
param	O campo da requisição responsável pela falha, quando a falha nomeia um. Nulo caso contrário.
code	O código de erro específico da Bayle. Nulo quando a falha não pôde ser identificada.

Trate por code, não por message

message é prosa e é traduzida, então casar com ela quebra na primeira vez que alguém enviar Accept-Language: pt-BR. code é estável e legível por máquina.

Um code nulo significa que a Bayle não conseguiu identificar a falha específica. O envelope continua válido e type continua significativo, então trate nulo como “algo deu errado que não está na lista abaixo”, não como um erro em si mesmo.

Tipos de erro

Tipo	Geralmente significa
invalid_request_error	A requisição está malformada ou um campo é inaceitável. Corrija e tente de novo.
authentication_error	A credencial está ausente ou é inválida.
permission_error	A credencial é válida mas não está autorizada para isso.
not_found_error	O modelo, job ou recurso nomeado não existe.
insufficient_quota	Sem saldo, ou um limite de gasto foi atingido.
rate_limit_error	Requisições demais, ou o modelo está sobrecarregado. Recue e tente de novo.
api_error	Uma falha do nosso lado. Tentar de novo é razoável.

Status codes

Status	Significado
400	Requisição inválida.
401	Credencial ausente ou inválida. Nada é cobrado.
403	Não autorizado para esta ação ou modelo.
404	Modelo, job ou mídia não encontrado.
409	Consentimento de vídeo necessário. Veja o guia de vídeo. Nada é cobrado.
413	A requisição, ou a resposta, excedeu um teto de tamanho.
429	Rate limited, ou o modelo está sobrecarregado.
500	Uma falha do nosso lado.
502	Não conseguimos alcançar o backend de geração. Tentar de novo é razoável.
504	A própria requisição demorou demais para ser concluída e expirou. Veja Tentando de novo — repetir sem alterações tende a esbarrar no mesmo limite de novo.

Todo código de erro

40 códigos. param é exibido onde a falha nomeia um campo específico da requisição.

Código	Tipo	Param	Mensagem
api_access_disabled	permission_error	—	API access has been disabled for this Bayle account.
audio_transcription_failed	api_error	—	Bayle could not complete this audio transcription due to a temporary error. Please retry.
audio_validation_failed	invalid_request_error	—	Bayle could not process this audio for transcription. Please check the file and try again.
character_not_found	not_found_error	character_slug	Bayle could not find a character matching the provided identifier.
content_policy_violation	invalid_request_error	—	Bayle's content policy does not permit this prompt.
context_length_exceeded	invalid_request_error	messages	This request exceeds the model's maximum context length supported by Bayle.
corrupted_image	invalid_request_error	—	Bayle could not read the image file because it is corrupted.
image_edit_failed	api_error	—	Bayle could not complete this image edit.
image_too_large	invalid_request_error	—	This image's dimensions exceed the maximum Bayle allows.
image_too_small	invalid_request_error	—	The image provided to Bayle is smaller than the minimum allowed dimensions.
inference_failed	api_error	—	Bayle could not complete inference for this request.
insufficient_quota	insufficient_quota	—	Your Bayle account does not have enough balance to complete this request.
invalid_api_key	authentication_error	—	Your Bayle API key is invalid.
invalid_audio_format	invalid_request_error	—	Bayle does not support the audio format provided.
invalid_content_type	invalid_request_error	—	Bayle does not support the content type of this request.
invalid_model	invalid_request_error	model	The model specified in this Bayle request is invalid.
invalid_request	invalid_request_error	—	Bayle could not process this request because one or more parameters are invalid.
invalid_signature	authentication_error	—	The sign-in signature provided to Bayle is invalid.
invalid_video_format	invalid_request_error	—	Bayle does not support the video format provided.
media_not_found	not_found_error	—	Bayle could not find the requested media. It may be invalid, expired, or deleted.
model_at_capacity	api_error	—	This model is at capacity on Bayle. Please try again shortly.
model_not_found	not_found_error	model	Bayle could not find the specified model.
model_offline	api_error	—	This model is temporarily offline on Bayle. Please try again shortly.
model_overloaded	rate_limit_error	—	This model is temporarily overloaded on Bayle. Please try again shortly.
model_requires_upgrade	permission_error	model	This model requires a Bayle Pro subscription.
payload_too_large	invalid_request_error	—	This request body is too large for Bayle to accept. Please reduce its size.
permission_denied	permission_error	—	Your Bayle credentials do not authorize this action.
rate_limit_exceeded	rate_limit_error	—	You have exceeded the rate limit for Bayle's API.
request_id_not_found	invalid_request_error	request_id	Bayle could not find a request matching the given request ID.
request_timeout	api_error	—	This request took too long to complete on Bayle and was timed out. For long-running requests, use streaming.
secondary_spend_limit_exceeded	insufficient_quota	—	This Bayle API key has reached its configured spending limit for this balance type.
subscription_inactive	authentication_error	—	Your Bayle Pro subscription is inactive.
tee_attestation_failed	api_error	—	Bayle could not complete a required secure-environment attestation for this request.
tee_signature_failed	api_error	—	Bayle could not complete a required secure-environment signature for this request.
unknown_error	api_error	—	Bayle encountered an unknown error while processing this request.
upscale_failed	api_error	—	Bayle could not upscale this image.
usd_spend_limit_exceeded	insufficient_quota	—	This Bayle API key has reached its configured USD spending limit.
video_duration_too_long	invalid_request_error	—	This video's duration exceeds the maximum Bayle allows.
video_duration_too_short	invalid_request_error	—	This video's duration is shorter than the minimum Bayle allows.
wallet_mismatch	permission_error	—	This Bayle request references a wallet that does not belong to this account.

Tentando de novo

Tente de novo 429, 500 e 502. Use backoff exponencial com jitter, e desista depois de algumas tentativas em vez de insistir sem parar.

504 é diferente: significa que a própria requisição demorou mais do que o limite de tempo do endpoint, então reenviar a mesma requisição tende a esbarrar nesse limite de novo. Só tente de novo depois de mudar algo que afete a duração da requisição — um prompt mais curto, outro modelo, ou uma saída menor — em vez de reenviá-la sem alterações.

Não tente de novo 400, 401, 403, 404, ou 413. Nada sobre a requisição vai ter mudado, então a resposta também não vai. 409 é um caso especial: não é bem uma nova tentativa, e sim um reenvio com um objeto de consentimento adicionado, descrito em o guia de vídeo.

Erros durante um stream

Uma chat completion em streaming confirma seu 200 antes da geração terminar, então uma falha posterior não pode mudar o status. Ela chega como um evento dentro do stream, carregando esse mesmo envelope. Veja Streaming.