Visual Layer Documentation: Visual Intelligence, At Scale

The Visual Layer API uses standard HTTP status codes. All error responses include a detail field describing what went wrong.

Error Response Format

Every error returns a JSON body with a single detail field:

{
  "detail": "Dataset ad48d250-1232-11f1-bfca-fa39f6ed1f22 has no embedding_config — index the dataset first."
}

HTTP Status Codes

Code	Meaning
200	Success.
202	Accepted — request received, processing started asynchronously.
400	Bad Request — check your request parameters.
401	Unauthorized — your JWT token is missing, invalid, or expired.
403	Forbidden — insufficient permissions or feature disabled.
404	Not Found — resource does not exist or you do not have access.
409	Conflict — resource state prevents the operation (for example, dataset not in `READY` status).
422	Unprocessable Entity — invalid parameter format or value.
500	Internal Server Error — contact support if this persists.

Python Error Handling

All code examples in this documentation call raise_for_status(), which raises an exception on any 4xx or 5xx response. Use the following pattern to catch errors and read the detail message:

import requests

try:
    resp = requests.post(url, headers=headers, data=payload)
    resp.raise_for_status()
except requests.exceptions.HTTPError as e:
    detail = e.response.json().get("detail", e.response.text)
    print(f"Error {e.response.status_code}: {detail}")
    raise

Authentication

Generate the JWT token required for all API calls.

Retrieve Dataset Status

Check dataset status before running operations.

Authentication

Create a Dataset from an S3 Bucket

⌘I

API Getting Started

Create a Dataset

Manage Datasets

Search

Guides

Self-Hosted Administration

Useful Scripts

Error Handling

Error Response Format

HTTP Status Codes

Python Error Handling

Authentication

Retrieve Dataset Status

​Error Response Format

​HTTP Status Codes

​Python Error Handling

​Related Resources

Authentication

Retrieve Dataset Status

Error Response Format

HTTP Status Codes

Python Error Handling

Related Resources