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

# Upstream Error

> Processing service unreachable, unavailable, or timed out

**HTTP Status:** 502, 503 or 504

```json theme={null}
{
  "code": "upstream_error",
  "message": "The processing service is temporarily unavailable. Retry with exponential backoff.",
  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
  "doc_url": "https://docs.poof.bg/errors/upstream-error"
}
```

## Reasons and How to Fix

### Temporary Processing Failure

The API gateway could not get a result from the image processing service. The status tells you why:

| Status | Meaning |
| - | - |
| 502 | Processing service unreachable |
| 503 | Processing service temporarily unavailable |
| 504 | Processing service timed out |

All three are transient and safe to retry. The failed request is not billed.

**To fix:**

1. Wait a few seconds and retry the request
2. Use exponential backoff for automatic retries
3. Check [status.poof.bg](https://status.poof.bg) for any ongoing incidents

### Retry Strategy

```python theme={null}
import time
import os
from poof import Poof, ServerError

client = Poof(api_key=os.environ["POOF_API_KEY"])

def process_with_retry(image_path, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.remove_background(image_path)
        except ServerError as e:
            if e.code == "upstream_error" and attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 1s, 2s, 4s
            else:
                raise
```

### Persistent Failures on One Image

If only a specific image keeps failing, the problem is usually the image itself, and you will typically see [`invalid_image`](/errors/invalid-image) or [`processing_failed`](/errors/processing-failed) instead.

**To fix:**

* Verify the image opens correctly in an image viewer
* Try converting to a standard JPEG or PNG
* Try a smaller version of the image

## Service Status

Check [status.poof.bg](https://status.poof.bg) for real-time service status and incident reports.

## Need Help?

If the issue persists, contact us at [support@poof.bg](mailto:support@poof.bg) with your `request_id` and the image (if possible).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.