Why did my request fail?

Last updated: June 12, 2026

If an API request fails, the response uses a standard HTTP status code, and asynchronous generation results carry a status field. Here is what each one means and what to do.

HTTP status codes

Code	Meaning	What to do
400 Bad Request	Malformed request or invalid parameters	Check your request body and parameter formats.
402 Payment Required	Insufficient credits	Add credits to your account, then retry.
403 Forbidden	API key lacks access to the resource	Check the key is valid and for the right environment.
422 Unprocessable Entity	Invalid request body or parameters	Correct the flagged fields and resubmit.
429 Too Many Requests	You exceeded your concurrency limit	Back off and retry once a previous task finishes.
500 Internal Server Error	Unexpected error on our side	Retry with exponential backoff; if it persists, contact support.
503 Service Unavailable	Temporary unavailability or high load	Wait a few moments and retry.

Generation result statuses

When you poll a request with its polling_url, the status field is one of:

Status	Meaning
Ready	Generation complete; the result is available to download.
Pending	Still processing; keep polling.
Request Moderated	Input flagged before processing. Not charged.
Content Moderated	Output flagged after processing. Not charged.
Task not found	The task ID does not exist or has expired.
Error	Processing failed; check the error details.

Handling transient errors (500 / 503 / 429)

These are usually temporary. Retry with exponential backoff (for example wait 1s, then 2s, then 4s) rather than retrying immediately in a tight loop. A short retry is almost always enough.

Still failing?

Check current service status at status.bfl.ml, and if a 500 persists, reach out to support@blackforestlabs.ai with your request ID so we can investigate.