Errors

Every error, on every endpoint, uses the same envelope:

{
  "error": {
    "message": "Your Bayle API key is missing or could not be verified.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

All four fields are always present. param and code may be null.

Field	Meaning
message	Human-readable, and localized. See Response language.
type	OpenAI’s error type vocabulary, so an SDK’s exception mapping keeps working.
param	The request field at fault, when the failure names one. Null otherwise.
code	Bayle’s specific error code. Null when the failure could not be identified.

Branch on code, not on message

message is prose and it is translated, so matching on it breaks the first time someone sends Accept-Language: pt-BR. code is stable and machine-readable.

A null code means Bayle could not identify the specific failure. The envelope is still valid and type is still meaningful, so treat null as “something went wrong that isn’t in the list below” rather than as an error in itself.

Error types

Type	Usually means
invalid_request_error	The request is malformed or a field is unacceptable. Fix and retry.
authentication_error	The credential is missing or invalid.
permission_error	The credential is valid but not authorized for this.
not_found_error	The named model, job, or resource does not exist.
insufficient_quota	No balance, or a spending limit reached.
rate_limit_error	Too many requests, or the model is overloaded. Back off and retry.
api_error	A failure on our side. Retrying is reasonable.

Status codes

Status	Meaning
400	Invalid request.
401	Missing or invalid credential. Nothing is charged.
403	Not authorized for this action or model.
404	Model, job, or media not found.
409	Video consent required. See the video guide. Nothing is charged.
413	The request, or the response, exceeded a size ceiling.
429	Rate limited, or the model is overloaded.
500	A failure on our side.
502	We could not reach the generation backend. Retrying is reasonable.
504	The request itself took too long to complete and was timed out. See Retrying — an unmodified retry is likely to hit the same limit again.

Every error code

40 codes. param is shown where the failure names a specific request field.

Code	Type	Param	Message
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.

Retrying

Retry 429, 500, and 502. Use exponential backoff with jitter, and give up after a few attempts rather than hammering.

504 is different: it means the request itself took longer than the endpoint’s own time limit, so resending the exact same request is likely to hit that limit again. Only retry it after changing something that affects how long the request takes — a shorter prompt, a different model, or a smaller output — rather than resending it unmodified.

Do not retry 400, 401, 403, 404, or 413. Nothing about the request will have changed, so the answer will not either. 409 is a special case: it is not a retry so much as a resubmission with a consent object added, described in the video guide.

Errors during a stream

A streaming chat completion commits its 200 before generation finishes, so a later failure cannot change the status. It arrives as an event inside the stream instead, carrying this same envelope. See Streaming.