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

# Errors

> Current public API error envelope and common error codes

All error responses use this envelope:

```json theme={"theme":"css-variables"}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Public message"
  },
  "request_id": "18b2ad5e-2a9e-4d3f-b9a8-9f2a1e0b1234"
}
```

Validation errors may also include `error.details`, an array of field-level validation messages.

The same request id is also sent as the `X-Request-Id` response header. Include it when contacting support.

## Common Error Codes

<div className="doc-table-scroll">
  <table>
    <thead>
      <tr>
        <th>HTTP</th>
        <th>Code</th>
        <th>Typical Cause</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>400</td>
        <td><code>VALIDATION\_ERROR</code></td>
        <td>Request payload failed validation</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>INVALID\_PERSONA</code></td>
        <td>Persona id is not a valid UUID</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>INVALID\_STYLE</code></td>
        <td>Style id is not a valid UUID</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>INVALID\_AMOUNT</code></td>
        <td>Amount is invalid or negative</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>CONTENT\_POLICY</code></td>
        <td>Request blocked by content policy</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>CANNOT\_DELETE\_PROCESSING</code></td>
        <td>Attempted to delete a persona or style while processing</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>SUPPORT\_IMAGE\_NOT\_SUPPORTED</code></td>
        <td>Support image is not available on the selected model</td>
      </tr>

      <tr>
        <td>413</td>
        <td><code>IMAGE\_TOO\_LARGE</code></td>
        <td>Input image exceeds the 10 MB size limit</td>
      </tr>

      <tr>
        <td>401</td>
        <td><code>MISSING\_API\_KEY</code></td>
        <td>Missing <code>X-Api-Key</code> header</td>
      </tr>

      <tr>
        <td>401</td>
        <td><code>INVALID\_API\_KEY\_FORMAT</code></td>
        <td>API key does not start with <code>pkz\_</code></td>
      </tr>

      <tr>
        <td>401</td>
        <td><code>INVALID\_API\_KEY</code></td>
        <td>API key is unknown</td>
      </tr>

      <tr>
        <td>401</td>
        <td><code>API\_KEY\_INACTIVE</code></td>
        <td>API key is disabled</td>
      </tr>

      <tr>
        <td>401</td>
        <td><code>API\_KEY\_DELETED</code></td>
        <td>API key was deleted</td>
      </tr>

      <tr>
        <td>402</td>
        <td><code>INSUFFICIENT\_CREDITS</code></td>
        <td>API balance is too low for the requested operation, or Smart Balance is enabled but the configured top-up cannot cover this request</td>
      </tr>

      <tr>
        <td>402</td>
        <td><code>SMART\_BALANCE\_PAYMENT\_FAILED</code></td>
        <td>Smart Balance is paused because the automatic top-up payment could not be processed</td>
      </tr>

      <tr>
        <td>403</td>
        <td><code>API\_ACCESS\_NOT\_ENABLED</code></td>
        <td>Account does not have API access</td>
      </tr>

      <tr>
        <td>403</td>
        <td><code>ACCOUNT\_SUSPENDED</code></td>
        <td>Account is suspended</td>
      </tr>

      <tr>
        <td>404</td>
        <td><code>NOT\_FOUND</code></td>
        <td>Requested resource or route was not found</td>
      </tr>

      <tr>
        <td>409</td>
        <td><code>NAME\_RESERVED</code></td>
        <td>Persona or style name is reserved</td>
      </tr>

      <tr>
        <td>409</td>
        <td><code>NAME\_ALREADY\_EXISTS</code></td>
        <td>Persona or style name already in use</td>
      </tr>

      <tr>
        <td>409</td>
        <td><code>CONFLICT</code></td>
        <td>Request conflicts with existing state</td>
      </tr>

      <tr>
        <td>422</td>
        <td><code>GENERATION\_REJECTED</code></td>
        <td>Request could not be processed</td>
      </tr>

      <tr>
        <td>499</td>
        <td><code>CANCELLED</code></td>
        <td>Generation was cancelled</td>
      </tr>

      <tr>
        <td>500</td>
        <td><code>GENERATION\_FAILED</code></td>
        <td>Generation request failed</td>
      </tr>

      <tr>
        <td>400</td>
        <td><code>INVALID\_IMAGE</code></td>
        <td>Image URL/body is invalid or not an accessible image</td>
      </tr>

      <tr>
        <td>500</td>
        <td><code>INTERNAL\_ERROR</code></td>
        <td>Unexpected server error</td>
      </tr>

      <tr>
        <td>503</td>
        <td><code>SERVICE\_UNDER\_MAINTENANCE</code></td>
        <td>Service maintenance window is active</td>
      </tr>

      <tr>
        <td>504</td>
        <td><code>GENERATION\_TIMEOUT</code></td>
        <td>Generation request exceeded timeout</td>
      </tr>

      <tr>
        <td>504</td>
        <td><code>SCORING\_TIMEOUT</code></td>
        <td>Thumbnail scoring exceeded timeout</td>
      </tr>

      <tr>
        <td>504</td>
        <td><code>TITLE\_TIMEOUT</code></td>
        <td>Title generation exceeded timeout</td>
      </tr>

      <tr>
        <td>429</td>
        <td><code>TOO\_MANY\_REQUESTS</code></td>
        <td>Rate limit exceeded</td>
      </tr>
    </tbody>
  </table>
</div>

Error codes may expand over time. Use `code` for programmatic handling and use `message` for a safe public summary.