> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixcraft.es/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete list of API error codes and how to resolve them.

# Error Codes

All API errors follow a consistent format:

```json theme={null}
{
  "error": true,
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error.",
  "docs": "https://docs.pixcraft.es/errors/ERROR_CODE"
}
```

## Error reference

| Code                     | HTTP Status | Description                                  | Solution                                              |
| ------------------------ | ----------- | -------------------------------------------- | ----------------------------------------------------- |
| `MISSING_API_KEY`        | 401         | No `Authorization` header in the request     | Add `Authorization: Bearer YOUR_KEY` header           |
| `INVALID_API_KEY`        | 401         | The API key was not found in the database    | Check that you copied the full key correctly          |
| `INACTIVE_API_KEY`       | 401         | The key exists but has been deactivated      | Contact support or create a new key in your dashboard |
| `RATE_LIMIT_EXCEEDED`    | 429         | Monthly API call limit reached               | Wait for the next billing period or upgrade your plan |
| `INVALID_NICHE`          | 400         | Niche ID doesn't exist or isn't on your plan | Call `GET /api/v1/niches` to see available niches     |
| `INVALID_IMAGE`          | 400         | Image could not be decoded                   | Ensure the image is a valid JPEG, PNG, or WebP        |
| `IMAGE_TOO_LARGE`        | 400         | Image exceeds 10MB                           | Resize or compress the image before sending           |
| `MISSING_REQUIRED_FIELD` | 400         | A required parameter is missing              | Check the endpoint docs for required fields           |
| `INVALID_DIMENSIONS`     | 400         | Width or height outside valid range          | Dimensions must be between 10 and 1000 cm             |
| `PROCESSING_ERROR`       | 500         | Internal error during pattern generation     | Retry the request. If persistent, contact support     |

## Handling errors in code

### JavaScript

```javascript theme={null}
const response = await fetch('https://www.pixcraft.es/api/v1/generate', { ... });

if (!response.ok) {
  const error = await response.json();
  switch (error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      // Wait and retry
      break;
    case 'INVALID_IMAGE':
      // Ask user to upload a different image
      break;
    default:
      console.error(`API Error: ${error.code} — ${error.message}`);
  }
}
```

### Python

```python theme={null}
response = requests.post('https://www.pixcraft.es/api/v1/generate', ...)

if response.status_code != 200:
    error = response.json()
    if error['code'] == 'RATE_LIMIT_EXCEEDED':
        time.sleep(60)
        # retry
    else:
        raise Exception(f"PixCraft error: {error['code']} — {error['message']}")
```

## Getting help

If you encounter a `PROCESSING_ERROR` that persists after retrying, contact us at [hola@pixcraft.es](mailto:hola@pixcraft.es) with:

* Your API key ID (not the full key)
* The request body you sent
* The full error response