Error Codes

All API errors follow a consistent format:

{
  "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

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

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 with:

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