# Ingest vision images

Content Enrichment API / Vision AI

`POST https://api.ygo.ai/v2/project/content/vision/ingestImages`

Submit image URLs for analysis; each gets an image ID immediately.

Asynchronous: poll the IDs with `getVisionImages` until `completed` or `failed`.

- 1-100 images per request, each `URL` absolute `https`.
- At most one selector (`HotelID`, `GlobalHotelID` or `ExternalHotelID`), or none; `HotelName` required with one, refused without.
- Except `giata` alone, a selector reaches only your project's hotels, your placeholder hotel (no selector, or its HotelID) and draft hotels holding images you submitted and have not deleted. Any other hotel answers like an unknown one: 404, as does a project without Vision AI.
- Only `giata` alone can create a hotel.
- 429: daily cap reached (25,000 images or 1,000 new hotels per rolling 24 hours); wait `Retry-After` seconds.

Exact spec (OpenAPI 3.0, JSON): https://docs.ygo.ai/reference/ingestVisionImages.json

## Example request

```bash
curl -X POST 'https://api.ygo.ai/v2/project/content/vision/ingestImages' \
  -H "Authorization: Bearer $YGO_API_KEY" \
  -H "X-Project-ID: $YGO_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "Images": [
    {
      "URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/"
    },
    {
      "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/"
    }
  ]
}'
```

## Authorization

`Authorization: Bearer <key>`

Project-scoped API key

## Headers

- `X-Project-ID` (string (uuid), **required**)

  Project UUID. Required for all project-scoped endpoints.

  Example: `$YGO_PROJECT_ID`

## Request body

Required.

### application/json

Schema: object, `IngestVisionImagesRequest`

Request body for submitting image URLs. Provide at most one hotel selector, or none to submit images without a hotel.

- `HotelID` (string (uuid))

  Hotel UUID, one of three optional, mutually exclusive selectors. Resolves only: an unknown UUID or a hotel you cannot reach (see the operation description) returns 404.

  Example: `0192fb17-5dc6-7abc-8def-123456789abc`
- `GlobalHotelID` (string)

  Cross-tenant global hotel identifier, one of three optional and mutually exclusive selectors. Resolves only: an unknown identifier or a hotel you cannot reach (see the operation description) returns 404.

  Example: `ES-MALLR-K7MP2`
- `ExternalHotelID` (map of string to string)

  Your own hotel identifiers, sub-keys `productid` and `giata`, AND-combined. Unless `giata` is alone, a hotel you cannot reach (see the operation description) returns 404; only `giata` alone can create one.

  Example:

  ```json
  {
    "productid": "IBS-MAJ-4711"
  }
  ```
- `HotelName` (string)

  Name of the hotel, required with a selector and refused without one, max 500 characters. Used only when a hotel is created, never written onto one that already exists.

  Example: `Hotel Bahia Azul`

  Limits: max length 500
- `Images` (array of object, `VisionImageSubmission`, **required**)

  The images to submit, between 1 and 100 per request. Every entry belongs to the hotel this request selects, or to the project's placeholder hotel when no selector is sent.

  Each item: One image URL submitted for analysis, with an optional room reference.

  Limits: min items 1, max items 100

  - `URL` (string (uri), **required**)

    Absolute https URL of the image. Maximum 4096 characters.

    Example: `https://images.example-client.com/1234567/room-dbl-sea-1.jpg`

    Limits: max length 4096
  - `RoomRef` (string)

    Optional room code or name from your own system, stored with the submission and echoed back by getVisionImages. Maximum 200 characters.

    Example: `DBL-SEA`

    Limits: max length 200

#### Example request: withoutHotel. Two images submitted without a hotel

```json
{
  "Images": [
    {
      "URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/"
    },
    {
      "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/"
    }
  ]
}
```

#### Example request: singleImage. One image for a hotel identified by your own product code

```json
{
  "ExternalHotelID": {
    "productid": "IBS-MAJ-4711"
  },
  "HotelName": "Hotel Bahia Azul",
  "Images": [
    {
      "URL": "https://images.example-client.com/1234567/exterior-pool.jpg"
    }
  ]
}
```

#### Example request: batchWithRoomRefs. Three images for a known hotel selected by its UUID, two carrying the client's room codes

```json
{
  "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
  "HotelName": "Hotel Bahia Azul",
  "Images": [
    {
      "URL": "https://images.example-client.com/1234567/lobby.jpg"
    },
    {
      "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
      "RoomRef": "DBL-SEA"
    },
    {
      "URL": "https://images.example-client.com/1234567/room-suite-1.jpg",
      "RoomRef": "SUITE-1"
    }
  ]
}
```

#### Example request: resubmission. Re-submitting two already known URLs alongside a new one

```json
{
  "ExternalHotelID": {
    "productid": "IBS-MAJ-4711"
  },
  "HotelName": "Hotel Bahia Azul",
  "Images": [
    {
      "URL": "https://images.example-client.com/1234567/lobby.jpg"
    },
    {
      "URL": "https://images.example-client.com/1234567/restaurant.jpg"
    },
    {
      "URL": "https://images.example-client.com/1234567/spa-old.jpg"
    }
  ]
}
```

#### Example request: createByGiata. Creating a hotel record: giata alone, not yet known

```json
{
  "ExternalHotelID": {
    "giata": "1234567"
  },
  "HotelName": "Hotel Bahia Azul",
  "Images": [
    {
      "URL": "https://images.example-client.com/1234567/exterior-pool.jpg"
    }
  ]
}
```

## Responses

### 200 OK

Images accepted. Every submitted URL has an image ID; analysis runs asynchronously, so poll the returned IDs with getVisionImages.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `IngestVisionImagesResponse`

Single-object response envelope wrapping the ingest result.

- `Data` (object, `IngestVisionImagesResult`, **required**)

  The hotel the images were attached to and the per-image outcome of the submission.

  - `HotelID` (string (uuid), **required**)

    UUID of the hotel the submitted images belong to. For a submission that named no hotel this is the project's placeholder hotel, and every later hotel-less submission returns that same ID.

    Example: `0192fb17-5dc6-7abc-8def-123456789abc`
  - `Images` (array of object, `IngestedImage`, **required**)

    One entry per submitted image, in request order.

    Each item: The outcome for one submitted image URL.

    - `ImageID` (string (uuid), **required**)

      Image UUID to poll with getVisionImages. For a URL that was already submitted for this hotel, this is the ID of the image that already carries it.

      Example: `0192fb20-1aa2-7def-9abc-1122334455aa`
    - `URL` (string (uri), **required**)

      The submitted image URL.

      Example: `https://images.example-client.com/1234567/exterior-pool.jpg`
    - `Status` (string, **required**)

      Current state of this image: `pending` keep polling, `completed` the result is ready to fetch, `failed` the URL could not be fetched. Fix a failed URL and submit it again.

      Values: `pending`, `completed`, `failed`

      Example: `pending`

##### Example: withoutHotel. Both images are queued for analysis on the project's placeholder hotel

```json
{
  "Data": {
    "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
    "Images": [
      {
        "ImageID": "0199b2d0-11a5-7c5e-8f21-6d0e4f88b521",
        "URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/",
        "Status": "pending"
      },
      {
        "ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
        "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
        "Status": "pending"
      }
    ]
  }
}
```

##### Example: singleImage. The product code resolved to a known hotel and the image is queued for analysis

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "Images": [
      {
        "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
        "URL": "https://images.example-client.com/1234567/exterior-pool.jpg",
        "Status": "pending"
      }
    ]
  }
}
```

##### Example: batchWithRoomRefs. Three new images attached to the hotel that already existed

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "Images": [
      {
        "ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
        "URL": "https://images.example-client.com/1234567/lobby.jpg",
        "Status": "pending"
      },
      {
        "ImageID": "0192fb22-3cc4-7def-9abc-3344556677cc",
        "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
        "Status": "pending"
      },
      {
        "ImageID": "0192fb23-4dd5-7def-9abc-4455667788dd",
        "URL": "https://images.example-client.com/1234567/room-suite-1.jpg",
        "Status": "pending"
      }
    ]
  }
}
```

##### Example: resubmission. One known URL is already analyzed, the other was confirmed unreachable earlier, and the new URL is queued

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "Images": [
      {
        "ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
        "URL": "https://images.example-client.com/1234567/lobby.jpg",
        "Status": "completed"
      },
      {
        "ImageID": "0192fb24-5ee6-7def-9abc-5566778899ee",
        "URL": "https://images.example-client.com/1234567/restaurant.jpg",
        "Status": "pending"
      },
      {
        "ImageID": "0192fb25-6ff7-7def-9abc-66778899aabb",
        "URL": "https://images.example-client.com/1234567/spa-old.jpg",
        "Status": "failed"
      }
    ]
  }
}
```

##### Example: createByGiata. A hotel record was created for the GIATA ID and the image is queued for analysis

```json
{
  "Data": {
    "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
    "Images": [
      {
        "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
        "URL": "https://images.example-client.com/1234567/exterior-pool.jpg",
        "Status": "pending"
      }
    ]
  }
}
```

### 400 Bad Request

Bad Request: the request body failed validation. No hotel and no image is stored when a request is rejected.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: multipleSelectors. More than one hotel selector

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "HotelID",
        "Message": "Provide exactly one of HotelID, GlobalHotelID, or ExternalHotelID (multiple were provided)"
      }
    ]
  }
}
```

##### Example: invalidHotelID. HotelID is not a valid UUID

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Invalid HotelID format"
  }
}
```

##### Example: invalidGiata. The giata sub-key is not a positive number

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "ExternalHotelID",
        "Message": "ExternalHotelID.giata must be a positive number"
      }
    ]
  }
}
```

##### Example: missingHotelName. HotelName missing on a submission that names a hotel

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "HotelName",
        "Message": "HotelName is required"
      }
    ]
  }
}
```

##### Example: hotelNameWithoutSelector. HotelName sent without a hotel selector

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "HotelName",
        "Message": "HotelName requires a hotel selector (HotelID, GlobalHotelID or ExternalHotelID); omit it to submit images without a hotel"
      }
    ]
  }
}
```

##### Example: tooManyImages. More than 100 images in one request

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "Images",
        "Message": "Images cannot exceed 100 entries"
      }
    ]
  }
}
```

##### Example: invalidImageURL. An image URL is not an absolute https URL, or a RoomRef is too long

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed",
    "Fields": [
      {
        "Field": "Images[3].URL",
        "Message": "URL must be an absolute https URL"
      },
      {
        "Field": "Images[5].RoomRef",
        "Message": "RoomRef cannot exceed 200 characters"
      }
    ]
  }
}
```

### 401 Unauthorized

Unauthorized: the API key is missing or invalid.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: invalidKey. Invalid API key

```json
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
```

### 403 Forbidden

Forbidden: the API key may not act on this project, or does not carry the `content.generation:write` permission this endpoint requires (`INSUFFICIENT_SCOPE`).

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: insufficientScope. Missing required scope

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.generation:write"
  }
}
```

##### Example: noProjectAccess. Project access required

```json
{
  "Error": {
    "Code": "FORBIDDEN",
    "Message": "Project access required"
  }
}
```

### 404 Not Found

Not Found: Vision AI is not enabled for your project, the project does not exist, or the selector matched no hotel you can reach. Nothing is stored.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: notFound. Project or resource not found

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Not found"
  }
}
```

##### Example: hotelNotFound. The selector matched no hotel you can reach, and could not create one

```json
{
  "Error": {
    "Code": "NOT_FOUND",
    "Message": "Hotel not found"
  }
}
```

### 409 Conflict

Conflict: the GIATA ID is held by a hotel record that is not available for submission.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: giataHeld. The GIATA ID cannot be used for a submission

```json
{
  "Error": {
    "Code": "ALREADY_EXISTS",
    "Message": "GiataID is held by a hotel record that is not available for submission"
  }
}
```

### 429 Too Many Requests

Too Many Requests: a per-project daily cap was reached, 25,000 images or 1,000 new hotels per rolling 24 hours. Nothing is stored or metered, and `Retry-After` carries the seconds to wait.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`
- `Retry-After` (integer)

  Number of seconds to wait before retrying the request. Present on 429 responses.

  Example: `30`

  Limits: min 1

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: rateLimited. Limit exceeded

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
```

##### Example: imageCapReached. Daily image submission cap reached (25,000 per rolling 24 hours), Retry-After: 3600

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Daily image submission limit reached for this project. Retry after the number of seconds in the Retry-After header."
  }
}
```

##### Example: hotelCapReached. Daily new-hotel cap reached (1,000 per rolling 24 hours), Retry-After: 3600

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Daily new-hotel limit reached for this project. Retry after the number of seconds in the Retry-After header."
  }
}
```

### 500 Internal Server Error

Internal Server Error: unexpected server error. Quote the `X-Trace-ID` response header when contacting support.

Headers:

- `X-Trace-ID` (string)

  Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.

  Example: `abc123def456ghi789`

#### application/json

Schema: object, `ErrorResponse`

Standard v2 error response wrapper.

- `Error` (object, `ErrorDetail`, **required**)

  Error detail containing a machine-readable code and human-readable message.

  - `Code` (string, **required**)

    Machine-readable error code for programmatic handling.

    Example: `VALIDATION_ERROR`
  - `Message` (string, **required**)

    Human-readable error message.

    Example: `Validation failed`
  - `Fields` (array of object, `FieldError`)

    Field-level validation errors. Only present for VALIDATION_ERROR responses.

    Each item: A single field-level validation error.

    - `Field` (string, **required**)

      Name of the field that failed validation. Per-image errors carry the image's position, for example Images[3].URL.

      Example: `Images[3].URL`
    - `Message` (string, **required**)

      Human-readable validation error message for this field.

      Example: `URL must be an absolute https URL`
    - `Code` (string)

      Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.

      Values: `REQUIRED`, `TOO_LONG`, `TOO_SHORT`, `OUT_OF_RANGE`, `TOO_MANY`, `INVALID_FORMAT`, `NOT_ALLOWED`, `CONFLICT`, `INVALID_ENCODING`, `INSECURE_SCHEME`, `UNSAFE_CONTENT`, `REQUIRED_WHEN_ENABLED`

      Example: `TOO_LONG`
    - `Params` (map of string to any)

      Machine-readable values the message is built from, such as limits or allowed values; keys are PascalCase and depend on Code. Optional.

      Example:

      ```json
      {
        "Max": 100
      }
      ```

##### Example: internalError. Internal server error

```json
{
  "Error": {
    "Code": "INTERNAL_ERROR",
    "Message": "Failed to store images"
  }
}
```
