Fix invalid_bg_color API Errors | BackgroundErase.com

A 400 invalid_bg_color response means the bg_color option was included in your request, but the value could not be parsed as a valid background color. The API validates this before the background replacement step runs, so the request fails early with a clear error message instead of trying to guess what you meant.

In most cases, this is a simple formatting issue. The safest fix is to retry with either a plain named color like white or a clean hex value like #FFFFFF. Once that works, you can switch to the exact color you want.

Fastest fix: retry the request with bg_color=white or bg_color=#FFFFFF. If that succeeds, the problem was the original color string, not the rest of the API request.

What this error looks like

A typical error response looks like this:

{
  "error": {
    "code": "invalid_bg_color",
    "message": "bg_color must be a valid hex or named color.",
    "status": 400,
    "request_id": "..."
  }
}

This tells you the issue is specifically with the bg_color value, not the image itself, not the API key, and not the core segmentation pipeline.

When bg_color is actually used

In BackgroundErase, bg_color is used when you want the cutout composited onto a solid background color instead of keeping transparency. This is especially common for formats like jpg, bmp, and gif, where a transparent alpha workflow is not usually the final goal.

If you are exporting png with transparency and do not actually need a flat solid background, you may not need bg_color at all. In that case, removing the option entirely can be the simplest solution.

Good rule: only send bg_color when you actually want a flattened background result.

The safest supported formats

The safest bg_color formats to use are:

Named colors like white, black, red, or navy
6-digit hex like #FFFFFF or FFFFFF
3-digit hex like #FFF or FFF

The API explicitly normalizes bare 3-digit and 6-digit hex strings, so values like FFF and FFFFFF can still work even without a leading #. Still, for readability and consistency, #FFFFFF is usually the best choice.

Examples that commonly fail

Most invalid_bg_color errors come from malformed strings, unsupported custom formats, or accidentally sending structured data instead of a plain string.

"#FFFF"
"##FFFFFF"
"FFFFF"
"bluish"
"255,255,255"
"[255,255,255]"

In practice, the safest path is not to get clever with color syntax. Use a straightforward named color or a clean hex string and keep the request simple.

Start with a minimal known-good request

The easiest way to isolate the issue is to retry with one direct request using a plain white background. If that works, your API key, image, and main request path are all fine.

Hex example:

curl -H 'x-api-key: YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/input.jpg' \
-F 'format=jpg' \
-F 'bg_color=#FFFFFF' \
-o output.jpg

Named-color example:

curl -H 'x-api-key: YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/input.jpg' \
-F 'format=jpg' \
-F 'bg_color=white' \
-o output.jpg

JSON example

If your workflow uses JSON, keep the bg_color value as a plain string:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "jpg",
  "bg_color": "#FFFFFF"
}

Do not send bg_color as an object, array, or custom RGB structure. The API is expecting a string value it can normalize and parse.

Python example for isolating the issue

In Python, the quickest test is a simple multipart request with a clean white background:

import requests

with open("input.jpg", "rb") as f:
    response = requests.post(
        "https://api.backgrounderase.com/v2",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"image_file": f},
        data={
            "format": "jpg",
            "bg_color": "#FFFFFF"
        },
        timeout=120,
    )

print(response.status_code)
print(response.text[:1000])

If that works, your issue is almost certainly the original color string rather than the rest of the request.

Node.js example for isolating the issue

In Node.js, the same pattern applies. Use a minimal known-good value first:

const fs = require("fs");
const FormData = require("form-data");

async function removeWithBackground() {
  const form = new FormData();
  form.append("image_file", fs.createReadStream("./input.jpg"));
  form.append("format", "jpg");
  form.append("bg_color", "#FFFFFF");

  const response = await fetch("https://api.backgrounderase.com/v2", {
    method: "POST",
    headers: {
      "x-api-key": process.env.BG_ERASE_API_KEY,
      ...form.getHeaders()
    },
    body: form
  });

  console.log(response.status);
  console.log(await response.text());
}

removeWithBackground();

Why this happens so often in real integrations

In real apps, bg_color often comes from user input, form builders, automation tools, or theme configuration. That makes it easy for bad values to sneak in through whitespace, invalid hex strings, mislabeled theme tokens, or UI values that look like colors to a person but are not actually parseable color strings.

This is especially common when a frontend stores colors in a custom structure like RGB objects, arrays, or app-specific token names and then passes those values directly into the API without converting them into a plain named color or hex string first.

Best practice: normalize color values in your own app before sending them to the API, and store them in one simple format such as 6-digit hex.

bg_color vs default white flattening

One subtle point is that opaque output formats like jpg, bmp, and gif are flattened onto a background color anyway. If you do not provide bg_color, the API falls back to white when it needs an opaque result.

That means if your goal is simply “make this JPG work,” you may not need to specify bg_color at all unless you want a specific non-white background.

Final resolution path

If you are seeing invalid_bg_color, the cleanest path is:

Decide whether you need bg_color at all
Retry with white or #FFFFFF
Use a plain string, not an object or array
Prefer 3-digit or 6-digit hex, or a standard named color
Remove malformed hashes, bad lengths, or custom tokens
Confirm the rest of the request works first
Then switch to your final intended color

In most cases, the issue is resolved immediately once the color string is simplified into a clean named color or hex value.