---
description: Clearcut api errors & troubleshooting. Learn how to remove image backgrounds, manage jobs and work with credits in your application.
title: API Errors & Troubleshooting | Clearcut
image: https://clearcut.sh/og/docs.png
---

GUIDES

[Quick start](https://clearcut.sh/docs)[Authentication](https://clearcut.sh/docs/authentication)[Credits & billing](https://clearcut.sh/docs/credits)[Limits & retries](https://clearcut.sh/docs/limits)[Examples](https://clearcut.sh/docs/examples)[Errors](https://clearcut.sh/docs/errors)

API REFERENCE

[POSTRemove a background](https://clearcut.sh/docs/remove-background)[GETremove.bg account info](https://clearcut.sh/docs/removebg-account)[POSTCreate an image job](https://clearcut.sh/docs/create-job)[GETGet a job](https://clearcut.sh/docs/get-job)[GETList images](https://clearcut.sh/docs/list-jobs)[DELETEDelete an image](https://clearcut.sh/docs/delete-job)[GETDownload a result](https://clearcut.sh/docs/download)[POSTExport an edited image](https://clearcut.sh/docs/export)[POSTUpload a background](https://clearcut.sh/docs/background)[POSTExport a ZIP batch](https://clearcut.sh/docs/batch-export)[POSTCopy a batch background](https://clearcut.sh/docs/batch-background)[POSTSmart Brush](https://clearcut.sh/docs/smart-brush)[POSTGenerate a scene](https://clearcut.sh/docs/generate-scene)[GETCredit balance](https://clearcut.sh/docs/account)[POSTRetry a failed image](https://clearcut.sh/docs/retry-job)[GETRecent usage](https://clearcut.sh/docs/usage)[Download OpenAPI](https://clearcut.sh/openapi.json)

Developer guide / Errors

# Errors

Handle the code, then show the message. Failed processing returns its credit reservation.

{
  "error": {
    "code": "insufficient_credits",
    "message": "You need more credits for this request."
  },
  "detail": "You need more credits for this request."
}

Responses from the remove.bg-compatible paths under `/v1.0/` also include `errors[].title` and `errors[].code`, as remove.bg clients expect.

| HTTP | Code                                        | What to do                                                                    |
| ---- | ------------------------------------------- | ----------------------------------------------------------------------------- |
| 400  | invalid\_form / invalid\_json               | Send a valid request body.                                                    |
| 401  | api\_key\_required / invalid\_api\_key      | Use an active API key.                                                        |
| 402  | insufficient\_credits                       | Add credits; no automatic overage is charged.                                 |
| 403  | origin\_not\_allowed                        | Use the website or a server-side API client.                                  |
| 404  | image\_not\_found                           | The image is not yours, was deleted or expired.                               |
| 409  | idempotency\_conflict / image\_not\_ready   | Use the same options with an existing key, or wait for processing.            |
| 410  | result\_expired                             | Use a new idempotency key for a new processing job.                           |
| 413  | too\_large                                  | Reduce the file or download binary instead of a large Base64 JSON response.   |
| 422  | invalid\_parameter / processing\_failed     | Check the source, resolution and options. Processing failures return credits. |
| 429  | rate\_limit / free\_limit / capacity\_limit | Respect Retry-After; avoid rapid retries.                                     |
| 502  | processing\_failed                          | Retry after a failed job; do not repeat a still-running job.                  |
| 503  | setup\_required                             | The service is not configured or is temporarily unavailable.                  |

Need help?

Prefer email? [support@clearcut.sh](mailto:support@clearcut.sh)

API Errors & Troubleshooting | Clearcut

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://clearcut.sh/#organization","name":"Clearcut","url":"https://clearcut.sh","logo":"https://clearcut.sh/apple-touch-icon.png","email":"support@clearcut.sh","description":"An independent image background removal service operated by chern0.dev.","contactPoint":{"@type":"ContactPoint","email":"support@clearcut.sh","contactType":"customer support"}},{"@type":"WebSite","@id":"https://clearcut.sh/#website","url":"https://clearcut.sh","name":"Clearcut","description":"Remove image backgrounds with Clearcut. Get 30 free credits every month for the website and API. Full-resolution downloads, no watermark. Packs from $3.","inLanguage":"en","publisher":{"@id":"https://clearcut.sh/#organization"}}]}
```