Troubleshooting 401: missing_api_key or invalid_api_key

What these 401 errors mean

BackgroundErase returns structured JSON errors for unauthorized requests. The two most common ones are shown below.

{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key.",
    "status": 401,
    "request_id": "..."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key.",
    "status": 401,
    "request_id": "..."
  }
}

• missing_api_key means no usable API key was found on the request
• invalid_api_key means a key was sent, but it was not accepted

These errors happen before image processing begins, so they are usually unrelated to the actual image file, mask generation, output format, or background settings.

Quick checklist

Before you debug your app code, walk through this checklist once. It fixes most 401 issues immediately.

1. Go to backgrounderase.com/account
2. Confirm your account has an active plan
3. If you do not have an active plan, get a Business plan
4. In the same account page, scroll to API Access
5. Create or copy your API key
6. Send the key in the x-api-key header
7. Retry with a single curl test before debugging your app

Step 1: Check your account and plan status

Go to backgrounderase.com/account and confirm that your account is in good standing. If you do not have an active plan, the safest next step is to get a Business plan before testing the API again.

Once your account is active, scroll down to the API Access section. That is where you create API keys and copy existing ones for use in your app, scripts, or automation flows.

Step 2: Create or copy an API key

If your request says missing_api_key, the first thing to verify is that you actually created a key in the account page. Many 401 issues come from testing the API before generating a real key in API Access.

If you already created a key, copy it again carefully from the account page and paste it directly into a simple test request. This helps rule out whitespace, old environment variables, or configuration drift in your application.

Step 3: Send the key in the recommended header

The recommended and simplest method is to send your key in the x-api-key header. This is the best place to start even if your stack supports other auth styles.

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

If that works, your key is valid and the problem is likely in how your app or deployment environment is passing the header.

Alternate auth formats the API can accept

The API can also accept certain authorization header formats, but for troubleshooting, x-api-key is still the most reliable and easiest to inspect.

curl -H 'Authorization: Bearer YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/image.jpg' \
-o output.png

If you are using a gateway, reverse proxy, serverless wrapper, or third-party connector, make sure it is not stripping or renaming the auth header before the request reaches the API.

Common causes of missing_api_key

• You never created an API key in the account page
• Your app is not sending the header at all
• The key is stored in an environment variable that is blank or missing in production
• A proxy, server action, or middleware is dropping the header
• You are testing from a frontend but forgot to move the key server-side
• You assumed website login credentials would work as API auth

In most of these cases, the fastest debug step is still to run one direct curl request from your terminal using a copied key from backgrounderase.com/account .

Common causes of invalid_api_key

• You copied the key incorrectly
• You are using an older revoked or replaced key
• You pasted extra spaces or quotes around the key
• Your deployment is using a different environment variable than your local machine
• The wrong secret is being injected into a worker, function, or container
• You are accidentally testing with a placeholder like YOUR_API_KEY

Test outside your app first

When a 401 appears inside a larger integration, the fastest way to isolate the issue is to test outside your application entirely. If a basic curl request succeeds, the problem is not the BackgroundErase account itself. It is somewhere in your app code, secret management, or request path.

This is especially useful for SaaS backends, serverless functions, Docker containers, CI jobs, automation tools, and third-party workflow builders where secret injection can differ by environment.

Node.js example for debugging a 401

If your app runs in Node.js, log the response status and body once so you can confirm exactly what the API is returning:

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

async function removeBackground(imagePath) {
  const form = new FormData();
  form.append("image_file", fs.createReadStream(imagePath));
  form.append("format", "png");

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

  if (!response.ok) {
    const text = await response.text();
    throw new Error(text);
  }

  return Buffer.from(await response.arrayBuffer());
}

Python example for debugging a 401

In Python, print the response status and part of the response body so you can quickly see whether the API returned missing_api_key or invalid_api_key.

import requests

API_KEY = "YOUR_API_KEY"

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

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

Environment and deployment issues that often cause 401s

Many teams find that local testing works, but staging or production returns 401. In most cases, that points to a secret management issue rather than a broken request format.

• Your local .env file has the key, but production does not
• A serverless platform is using an outdated environment variable
• A worker process was deployed before the latest secret was added
• A frontend-only environment variable is not available on the server
• A proxy or CDN configuration is stripping the auth header

This is why a direct curl check is so useful. It tells you whether the issue is account-level or deployment-level in just a few seconds.

Use the request ID when escalating an issue

Unauthorized API errors include a request_id in the JSON error response, and the API also returns an X-Request-ID header. If you need support, include that value along with the exact time of the request and whether you were testing from curl, your app, or an automation platform.

Final resolution path

If you are seeing missing_api_key or invalid_api_key, the cleanest path is:

• Go to backgrounderase.com/account
• Confirm your plan is active
• If you do not have an active plan, get a Business plan
• Scroll to API Access and create or recopy your API key
• Retry with the x-api-key header using curl first
• Only after that, move back into your app integration

In most cases, that resolves the issue without any deeper API debugging.