> ## 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.

# API Error Codes

> Complete reference of Poof API error codes

Below is a comprehensive list of all possible error codes you might encounter when using the Poof API. Each error includes a description, HTTP status code, and a link to detailed documentation about how to handle it.

## Error Reference Table

| Error Code | Description | HTTP Status |
| - | - | - |
| [authentication\_error](/errors/authentication-error) | `x-api-key` header missing or not recognised | 401 |
| [permission\_denied](/errors/permission-denied) | The endpoint or feature is not included in your current plan, or the key is not permitted | 403 |
| [payment\_required](/errors/payment-required) | Your plan's monthly credits are used up | 402 |
| [rate\_limit\_exceeded](/errors/rate-limit-exceeded) | Per-plan requests-per-minute limit or the global per-IP limit hit | 429 |
| [validation\_error](/errors/validation-error) | Bad parameter value or non-multipart body | 400 |
| [missing\_image](/errors/missing-image) | No `image_file` part in the request | 400 |
| [image\_too\_large](/errors/image-too-large) | Image exceeds 20 MB | 400 (413 when rejected by the processing service) |
| [invalid\_image](/errors/invalid-image) | File could not be decoded as PNG, JPEG or WebP | 422 |
| [processing\_failed](/errors/processing-failed) | The model or encoder failed on this image | 500 |
| [upstream\_error](/errors/upstream-error) | Processing service unreachable, temporarily unavailable, or timed out | 502 / 503 / 504 |
| [internal\_server\_error](/errors/internal-server-error) | Unexpected server error | 500 |
| `not_found` | Unknown path | 404 |

<Note>
  `image_too_large` is normally returned as `400` by the API gateway. If an oversized upload reaches the processing service, it is rejected there with `413`. Handle both statuses the same way.

  `upstream_error` uses `502` (unreachable), `503` (temporarily unavailable) or `504` (timed out). All three are safe to retry with backoff.
</Note>

## Error Response Format

All errors return a flat JSON body:

```json theme={null}
{
  "code": "validation_error",
  "message": "Invalid value for 'format': expected one of png, jpg, webp.",
  "details": {
    "format": [
      "must be one of: png, jpg, webp"
    ]
  },
  "request_id": "req_3f6a2c1e-9b0d-4e7a-8c21-5d1f0a9b7e42",
  "doc_url": "https://docs.poof.bg/errors/validation-error"
}
```

| Field | Description |
| - | - |
| `code` | Machine-readable error code from the table above |
| `message` | Human-readable description |
| `request_id` | Unique request ID (also sent as the `X-Request-ID` response header) |
| `doc_url` | Link to the documentation page for this error |
| `details` | Optional. For `validation_error` an object mapping field names to messages; otherwise a string or omitted |

Every error response also carries an `X-Request-ID` header equal to `request_id`. Failed requests are never billed.

The `request_id` is useful for support — include it when contacting [support@poof.bg](mailto:support@poof.bg) about an issue.


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