EyeQuant API Error Codes and HTTP Status Reference

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/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 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 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.
`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 for supported dimension limits.

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.

​Error response format

​Error codes

Error response format

Error codes