> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitstudio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle errors and recover safely

> Distinguish rejected requests from failed jobs, account actions, and uncertain submissions.

There are two places to handle failure: the HTTP response when submitting a request, and the status of an asynchronous job after it has been accepted.

For an accepted job, failures arrive through [`GET /v1/jobs/{id}`](/api-reference/jobs/get): `status` becomes `failed` or `policy_blocked`, `result` remains `null`, and `error.code` provides a safe classification. Stop polling at either terminal state. The HTTP error shapes below apply when a request itself is rejected.

## Parse the HTTP status and body

Some handlers return a simple error:

```json theme={null}
{"error": "image_ids is required"}
```

Others return structured account or validation information with fields such as `code`, `message`, `user_message`, `cta`, and `next_action`. Keep the status code and structured fields. For a readable message, prefer `user_message` or `message`, then `error`; do not assume every endpoint uses the same shape.

| Response                                    | Next step                                                                                                                             |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `400`                                       | Correct the body, source IDs, file format, dimensions, or model settings.                                                             |
| `401`                                       | Check the bearer key and access to the requested workspace or resource.                                                               |
| `402`, `403`, or an account-action response | Read the body for a scope, plan, feature, or credit restriction.                                                                      |
| `404`                                       | Check the resource ID and whether it is accessible in the key’s workspace.                                                            |
| `429`                                       | Reduce concurrency and back off. Honor `Retry-After` when present.                                                                    |
| `5xx`                                       | Record the response and investigate a temporary service failure. Confirm whether a creation request was accepted before resubmitting. |

If `cta` is true, surface the relevant account action in your application. Repeating the same request will not solve a missing plan, permission, or credit balance.

## Handle a failed job

Stop polling on `failed` or `policy_blocked`. When present, `failure_code` gives a broad category:

| Code                   | Recovery                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `input_rejected`       | Review the source media and request settings.                                                         |
| `provider_unavailable` | Check the failure detail and try again later if appropriate.                                          |
| `queue_timeout`        | The queued job did not finish in its allowed window. Inspect the job before starting another attempt. |
| `policy_blocked`       | Ask for revised source media or instructions that comply with the service’s rules.                    |

Save the job ID and `fail_reason` for support and for your own logs. These fields can be absent, so fall back to the status and the message shown in Studio.

## Retry reads carefully; reconcile writes first

Use bounded retries with backoff for temporary polling failures. Keep job IDs when a client deadline expires. Avoid an endless poll loop and stop on terminal states.

Do not blindly retry a generation, edit, upscale, or video POST after a network timeout: the operation may have been created even if its response was lost. Check recent images or the parent’s versions and reuse the existing job when found. There is no documented idempotency-key contract in this reference.

For support, send the endpoint, HTTP status, approximate UTC time, and image or version ID to [hello@bitstudio.ai](mailto:hello@bitstudio.ai). Redact API keys and Authorization headers.