# Errors

> FlyMy.AI error taxonomy: validation, rate limits, timeouts, server errors. How to detect each class and retry safely.

When an API request fails due to client-side input issues (like validation errors) or server-side problems, the API returns a structured error response. This response includes a standard HTTP status code, specific headers, and a JSON body detailing the errors.

## Error Response Structure

The error response consists of:

1. **HTTP Status Code:** Indicates the general category of the error (e.g., `500` for internal errors, `504` for timeouts).
2. **Headers:** Includes required headers like `X-FlyMyAI-Retryable`.
3. **JSON Body:** Contains a `detail` field which is an array of `Error` objects.

### Headers

| Header | Description |
|--------|-------------|
| X-FlyMyAI-Retryable | **[OPTIONAL]** A boolean ("true" or "false") indicating if retrying the exact same request might succeed (e.g., transient issues). |

### Error Object Structure

The `detail` field is an array where each object represents a specific error.

| Property | Description |
|----------|-------------|
| loc | **[REQUIRED]** An array indicating the location of the error (e.g., ["body", "field_name"] for input validation, ["body"] for general errors). |
| msg | **[REQUIRED]** A human-readable description of the error. Client code should not parse and rely on the msg field. |
| type | **[REQUIRED]** A unique, machine-readable string identifying the error category (e.g., image_too_large). Use this for conditional logic. |
| url | **[REQUIRED]** A link to documentation about this specific error type. |
| ctx | **[OPTIONAL]** An object with additional structured, machine-readable context for the error type. |
| input | **[OPTIONAL]** The input that caused the error. |

## Common Error Types

### `internal_server_error`

This error indicates an unexpected issue occurred on the server that prevented the request from being fulfilled.

* **Status Code:** 500
* **Retryable:** Can be `true` or `false`.

```json
[
  {
    "loc": ["body"],
    "msg": "Internal server error",
    "type": "internal_server_error",
    "url": "https://docs.flymy.ai/errors/#internal_server_error",
    "input": { "prompt": "a cat" }
  }
]
```

### `generation_timeout`

This error occurs when the requested operation took longer than the allowed time limit to complete.

* **Status Code:** 504
* **Retryable:** Can be `true` or `false`.

```json
[
  {
    "loc": ["body"],
    "msg": "Generation timeout",
    "type": "generation_timeout",
    "url": "https://docs.flymy.ai/errors/#generation_timeout",
    "input": { "prompt": "a very complex scene taking too long" }
  }
]
```

### `invalid_image_format`

This error indicates that the image file format is not supported by the endpoint.

* **Status Code:** 422
* **Retryable:** `false`.
* **Context (`ctx`):**
  * `supported_formats`: A list of supported image file extensions.

```json
[
  {
    "loc": ["body", "image"],
    "msg": "Unsupported image format. Supported formats are .jpg, .jpeg, .png, .webp.",
    "type": "invalid_image_format",
    "url": "https://docs.flymy.ai/errors/#invalid_image_format",
    "ctx": {
      "supported_formats": [".jpg", ".jpeg", ".png", ".webp"]
    },
    "input": "https://example.com/image.tiff"
  }
]
```

### `invalid_video_format`

This error indicates that the video file format is not supported by the endpoint.

* **Status Code:** 422
* **Retryable:** `false`.
* **Context (`ctx`):**
  * `supported_formats`: A list of supported video file extensions.

```json
[
  {
    "loc": ["body", "video_file"],
    "msg": "Unsupported video format. Supported formats are .mp4, .mov, .webm.",
    "type": "invalid_video_format",
    "url": "https://docs.flymy.ai/errors/#invalid_video_format",
    "ctx": {
      "supported_formats": [".mp4", ".mov", ".webm"]
    },
    "input": "https://example.com/video.avi"
  }
]
```

### `video_duration_too_long`

This error indicates that the provided video file exceeds the maximum allowed duration.

* **Status Code:** 422
* **Retryable:** `false`.
* **Context (`ctx`):**
  * `max_duration`: The maximum allowed duration in seconds.
  * `provided_duration`: The duration of the provided video file in seconds.

```json
[
  {
    "loc": ["body", "video_file"],
    "msg": "Video duration exceeds the maximum allowed. Maximum is 60 seconds, provided is 120 seconds.",
    "type": "video_duration_too_long",
    "url": "https://docs.flymy.ai/errors/#video_duration_too_long",
    "ctx": {
      "max_duration": 60,
      "provided_duration": 120
    },
    "input": "https://example.com/long_video.mp4"
  }
]
```

## Error Handling Best Practices

1. **For Machine Processing:**
   - Rely on the `type` field for conditional logic
   - Use `ctx` for specific error details if available
   - Check the `X-FlyMyAI-Retryable` header for retry decisions

2. **For Human Display:**
   - Use the `msg` field to show error messages to end-users
   - Client code should not parse and rely on the msg field

3. **For Documentation:**
   - Use the `url` field to link to further documentation about the specific error
   - This is primarily intended for developers to get more detailed information about error handling and resolution