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

# EyeQuant API Error Codes and HTTP Status Reference

> EyeQuant returns structured JSON error responses with error codes. Reference all error codes, HTTP status meanings, and how to resolve each error.

When something goes wrong with an API request, EyeQuant returns both an HTTP status code and a structured JSON error body so you know exactly what happened and how to fix it. This two-part approach gives you machine-readable codes you can branch on in code, alongside human-readable messages that make debugging fast.

## Error response format

EyeQuant communicates errors through two complementary channels:

* **HTTP status codes** — A code in the `400`–`499` range indicates a client error you can fix (for example, bad credentials or an invalid request body). A code in the `500`–`599` range indicates a server-side error within EyeQuant's own systems.
* **JSON error body** — Where possible, the response body contains an `error` object with two fields: `error.code` (a stable, machine-readable string) and `error.message` (a human-readable explanation). Concrete errors may include additional detail in the `message` field beyond what is listed here.

Here is an example of a full error response:

```http theme={null}
HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "authentication_failed",
    "message": "We were unable to authenticate you. Please check your credentials."
  }
}
```

Use `error.code` to drive programmatic error handling in your integration, and `error.message` to surface useful context in logs or user-facing feedback.

## Error codes

The table below covers all known error codes, what each one means, and how to resolve it.

| Code                             | Description                                                               | Resolution                                                                                               |
| -------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `client_error`                   | Generic client error — something is wrong with the request.               | Check the request body, headers, and parameters for mistakes.                                            |
| `server_error`                   | Generic server error — an error occurred in EyeQuant's system.            | EyeQuant has been alerted. Retry the request after a short delay.                                        |
| `resource_gone`                  | The requested resource is no longer accessible.                           | Results have expired. See [Result Expiry](/concepts/result-expiry) for details on retention windows.     |
| `authentication_failed`          | Missing or incorrect API credentials.                                     | Check your API key and ensure the `Authorization` header is set correctly.                               |
| `over_capacity`                  | The service is currently unavailable.                                     | Retry later. Check the [API Status](/reference/api-status) page for up-to-date availability information. |
| `invalid_input_configuration`    | The `input` object could not be used to start an analysis.                | Review the `error.message` field for specifics. See [Input Model](/concepts/input-model).                |
| `could_not_grab_web_page`        | EyeQuant could not capture the specified web page URL.                    | Verify the URL is valid and publicly accessible. Retry the request, or use an image input instead.       |
| `blank_input_image`              | The input image is a single solid color.                                  | Provide an image with visual content — solid-color images cannot be analyzed.                            |
| `unreadable_input_image`         | The input image could not be read — unsupported format or corrupted file. | Check the file format (PNG or JPEG only) and ensure the file is not truncated or corrupted.              |
| `invalid_input_image_dimensions` | The image dimensions are too small or too large.                          | See [Image Formats](/concepts/input-formats) for supported dimension limits.                             |

<Note>
  Server errors (5xx) are logged automatically and the EyeQuant team is notified immediately. If a server error persists across multiple retries, contact support for assistance.
</Note>