Errors

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.

[
  {
    "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.

[
  {
    "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.

[
  {
    "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.

[
  {
    "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.

[
  {
    "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