Resolving 422: validation_error

What a 422 validation_error looks like

BackgroundErase returns structured JSON for validation failures. A typical 422 response looks like this:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "status": 422,
    "request_id": "...",
    "details": [
      {
        "type": "...",
        "loc": ["..."],
        "msg": "...",
        "input": "..."
      }
    ]
  }
}

The details array usually contains the most useful clue. That is where FastAPI reports which part of the request could not be validated.

422 vs 400 in this API

This is one of the most important things to understand when troubleshooting BackgroundErase. In your orchestrator, many malformed request cases are deliberately handled as 400 instead of 422.

• Invalid JSON syntax is returned as 400 invalid JSON
• Missing image fields in JSON or multipart are usually returned as 400
• Invalid base64 is returned as 400 invalid_base64
• Unsupported size or format values are returned as 400
• Request-shape problems caught by FastAPI itself can show up as 422 validation_error

Quick checklist

Before changing your app code deeply, walk through this list:

1. Make sure you are calling POST /v2
2. Send only one image input path per request
3. For multipart, include image_file or image_base64 or image_url
4. For JSON, include image or image_base64 or image_url
5. Keep Content-Type aligned with the body you are actually sending
6. Do not wrap multipart uploads inside JSON
7. Retry first with a minimal direct curl example

What /v2 actually expects

The main API route is POST /v2. It accepts a few specific input patterns, and sticking to those is the best way to avoid validation problems.

For multipart/form-data, you should send one of these:

• image_file
• image_base64
• image_file_b64
• image_url

For application/json, you should send one of these:

• image for the legacy base64 path
• image_base64
• image_url

Additional options like format, size, crop, despill, and bg_color can be added, but the image input path must still be valid.

Use a clean multipart request first

The easiest baseline request is a multipart upload with image_file. If this works, the API itself is fine and your issue is probably in how another tool is generating the request.

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

Use a clean JSON request if your workflow needs JSON

If your client or automation platform sends JSON, keep the body simple and make sure the Content-Type is really application/json.

curl -H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
https://api.backgrounderase.com/v2 \
-d '{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "png",
  "size": "full"
}'

A valid JSON body can look like this:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "png",
  "size": "full",
  "crop": false,
  "despill": false
}

The legacy JSON base64 path also works:

{
  "image": "BASE64_IMAGE_HERE"
}

Common request-shape mistakes that can trigger 422

In real-world integrations, 422 errors often come from the layer building the request rather than the business logic itself. These are some of the most common causes:

• Sending JSON while labeling the request as multipart
• Sending multipart while forcing Content-Type: application/json
• Wrapping file uploads inside a JSON object instead of sending a true multipart file part
• Using the wrong HTTP method for the route
• Having an automation tool produce a malformed request body or nested object where a flat form field was expected
• A gateway or SDK transforming the body differently than you think

These are especially common in Zapier, Make, internal proxy layers, server actions, API gateways, low-code tools, and auto-generated clients.

What will not usually cause 422 here

Because of how your orchestrator is written, many mistakes do not become 422 at all. They usually come back as 400 instead. That includes:

• Malformed JSON syntax
• Invalid base64
• Missing image fields after parsing
• Unsupported format names
• Unsupported size names
• Invalid bg_color values

Check your client code with a minimal request

Once a minimal curl call works, compare your application request line by line against that known-good example. Usually the difference is in one of these places:

• Wrong content type header
• Unexpected body wrapper object
• File not sent as an actual file part
• Fields nested inside another object
• Automation tool serializing booleans or files strangely
• Wrong route or method

Python example for isolating the issue

If you are debugging from Python, first confirm the API works with a plain multipart request:

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": "png", "size": "full"},
        timeout=120,
    )

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

If that succeeds but your app still returns 422, the bug is in your app’s request construction rather than the API.

Node.js example for isolating the issue

In Node.js, the cleanest test is a simple multipart upload with FormData.

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

async function testRequest() {
  const form = new FormData();
  form.append("image_file", fs.createReadStream("./input.jpg"));
  form.append("format", "png");
  form.append("size", "full");

  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());
}

testRequest();

Automation platforms and gateways are common sources

If you are using a no-code platform, internal API gateway, server action, or proxy layer, 422 errors often appear because the tool is transforming the request before it ever reaches BackgroundErase. That can happen even when the UI makes the setup look correct.

Common examples include file inputs being converted into JSON metadata instead of actual file uploads, multipart fields being nested inside another object, or a custom connector forcing a content type that does not match the body.

Use the request details and request ID

The details array in a 422 response is often your best clue because it shows what FastAPI could not validate. The error response also includes a request_id, and the API adds an X-Request-ID response header.

If you need support, include the request ID, timestamp, the route you called, the content type you sent, and whether the request came from curl, your backend, or an automation platform.

Final resolution path

If you are seeing 422 validation_error, the cleanest path is:

• Confirm you are calling POST /v2
• Choose one valid request style: multipart or JSON
• Use one valid image field path for that request style
• Make sure the content type matches the actual body
• Test with a minimal direct curl example
• Then compare your app or tool against the working request
• Use the 422 details array and request ID if needed

In most cases, a 422 here is not about the image itself. It is about how the request was assembled before it reached the image-processing logic.