Error Codes

When making requests to the ForVoyez API, you may encounter various error codes and error messages that indicate the status of your request. This page provides a comprehensive list of the error codes and messages you may receive, along with their descriptions and possible solutions.

Error Response Format

When an error occurs, the ForVoyez API returns the HTTP status code of the error and a JSON body (Content-Type: application/json) with a single error field that contains a human-readable message. For example, a request without an Authorization header gets 401 Unauthorized with this body:

{
	"error": "Unauthorized, missing Authorization header"
}

A request that fails never uses a credit, whatever the error.

The /describe endpoint checks the API key and your credit balance before it reads the request body: a request with an invalid key gets a 401 even when its image is too large or missing. The /tokens endpoint has its own error messages, listed in /tokens Error Messages below.

HTTP Status Codes

The ForVoyez API uses standard HTTP status codes to indicate the success or failure of a request:

• 200 OK: The request was successful. 1 credit is used.
• 400 Bad Request: The body is not multipart/form-data, the image is missing or is not a JPEG, PNG, WebP, or GIF image, the schema is over the schema limits, or the requested fields need a longer answer than the API can return. With /tokens: the key was not created from the dashboard.
• 401 Unauthorized: The API key is missing, invalid, expired, or deleted. With /describe, also when your credit balance is empty.
• 404 Not Found: With /tokens only: the API key is valid but its account no longer exists.
• 413 Payload Too Large: With /describe only: the image is over 10 MB, or the request body is over 11 MB.
• 500 Internal Server Error: The metadata could not be generated (for example, the AI model failed or timed out), the image could not be processed, or another unexpected error occurred on the server side. No credit is used, so you can retry the request.

ForVoyez API Error Messages

Each error message of the /describe endpoint below comes with its status code and the exact JSON body the API returns.

400 Bad Request

• Bad Request, the body must be multipart/form-data

  • Status Code: 400
  • Body: {"error": "Bad Request, the body must be multipart/form-data"}
  • Description: The request body cannot be read as multipart/form-data: it is JSON, empty, or sent with a Content-Type: multipart/form-data header set by hand, without the boundary that separates the form fields.
  • Solution: Send a form (cURL -F, FormData in JavaScript, files= in Python requests) and let your HTTP client set the Content-Type header.

• Bad Request, No file uploaded

  • Status Code: 400
  • Body: {"error": "Bad Request, No file uploaded"}
  • Description: The request has no image field.
  • Solution: Send the image in the image field of a multipart/form-data request body.

• Bad Request, Invalid image file

  • Status Code: 400
  • Body: {"error": "Bad Request, Invalid image file"}
  • Description: The image field is not a JPEG, PNG, WebP, or GIF image. The API detects the format from the file content, not from the file name or the content type sent with the file: an SVG or TIFF image, or a text file renamed to photo.jpg, gets this error, whatever content type it is sent with.
  • Solution: Convert the image to JPEG, PNG, WebP, or GIF.

• Invalid schema: ... (schema limits)

  • Status Code: 400
  • Body, depending on the limit:
    • {"error": "Invalid schema: at most 20 fields are allowed"}
    • {"error": "Invalid schema: field names must be at most 64 characters"}
    • {"error": "Invalid schema: field descriptions must be at most 1000 characters"}
    • {"error": "Invalid schema: \"__proto__\" is not allowed as a field name"}
  • Description: The schema field is over the schema limits.
  • Solution: Reduce your schema to at most 20 fields, with field names up to 64 characters and descriptions up to 1,000 characters. See Data Schemas.

• Invalid schema: the requested fields need a longer answer than the API can return ... (answer too long)

  • Status Code: 400
  • Body: {"error": "Invalid schema: the requested fields need a longer answer than the API can return (about 1,500 words for all fields together), ask for fewer or shorter fields"}
  • Description: The schema asks for more text than one answer can hold, for example many fields that each ask for several paragraphs. The limit is about 1,500 words for all fields together.
  • Solution: Ask for fewer fields, or for shorter values in the field descriptions.

401 Unauthorized

• Unauthorized, missing Authorization header

  • Status Code: 401
  • Body: {"error": "Unauthorized, missing Authorization header"}
  • Description: The Authorization header is missing in the request, or it does not start with Bearer .
  • Solution: Send your API key in the Authorization: Bearer YOUR_API_KEY header.

• Unauthorized, invalid token

  • Status Code: 401
  • Body: {"error": "Unauthorized, invalid token"}
  • Description: The request lacks valid authentication credentials.
  • Possible Causes:
    • The provided API key is invalid or malformed.
    • The API key has passed the expiration date set when it was created.
    • The API key has been deleted from the dashboard (deleting a key revokes it immediately).
  • Solution: Create a new API key in the dashboard and update your application.

• Unauthorized, no credit left

  • Status Code: 401
  • Body: {"error": "Unauthorized, no credit left"}
  • Description: Your credit balance is empty.
  • Solution: Wait for your next subscription renewal, upgrade your plan, or buy a credit pack. See Limits and Quotas.

413 Payload Too Large

• Image too large: the maximum is 10 MB
  • Status Code: 413
  • Body: {"error": "Image too large: the maximum is 10 MB"}
  • Description: The image is over 10 MB, or the whole request body is over 11 MB. When the Content-Length header announces a body over 11 MB, the API answers before reading the upload. No credit is used.
  • Solution: Resize or compress the image to 10 MB or less. The API scales every image down to at most 1,000 pixels on its longest side before analysing it, so a smaller upload gives the same result.

500 Internal Server Error

• Internal Server Error

  • Status Code: 500
  • Body: {"error": "Internal Server Error"}
  • Description: The metadata could not be generated, for example because the AI model failed or did not answer in time, or another unexpected error occurred on the server side. No credit is used.
  • Solution: Retry the request after a short wait. If you encounter this error repeatedly, please contact our support team for assistance.

• Image processing failed: ...

  • Status Code: 500
  • Body, for example: {"error": "Image processing failed: VipsJpeg: premature end of JPEG image"}
  • Description: The file is a JPEG, PNG, WebP, or GIF image, but it could not be decoded, for example because it is truncated or corrupt. The rest of the message gives the cause. No credit is used.
  • Solution: Open the image in an image editor, save it again, and send the new file.

/tokens Error Messages

The GET /api/tokens endpoint, which checks an API key and returns its credit balance (see /tokens), answers with these messages. It never uses a credit, and an empty credit balance is not an error for it.

• Missing or invalid authentication token

  • Status Code: 401
  • Body: {"error": "Missing or invalid authentication token"}
  • Description: The Authorization header is missing, or it does not start with Bearer .
  • Solution: Send your API key in the Authorization: Bearer YOUR_API_KEY header.

• Invalid or expired token

  • Status Code: 401
  • Body: {"error": "Invalid or expired token"}
  • Description: The value sent is not a ForVoyez API key (for example a truncated copy), or the key has passed its expiration date.
  • Solution: Copy the whole key again, or create a new API key in the dashboard.

• Unauthorized, invalid token

  • Status Code: 401
  • Body: {"error": "Unauthorized, invalid token"}
  • Description: The API key has been deleted from the dashboard.
  • Solution: Create a new API key in the dashboard and update your application.

• Malformed token: missing userId

  • Status Code: 400
  • Body: {"error": "Malformed token: missing userId"}
  • Description: The key is signed by ForVoyez but was not created from the dashboard.
  • Solution: Create a new API key in the dashboard.

• User not found

  • Status Code: 404
  • Body: {"error": "User not found"}
  • Description: The API key is valid but the account it belongs to no longer exists.
  • Solution: Contact our support team.

• Server error

  • Status Code: 500
  • Body: {"error": "Server error"}
  • Description: An unexpected error occurred on the server side.
  • Solution: Retry the request after a short wait.

Handling Errors

When consuming the ForVoyez API, it's important to handle errors gracefully in your application. Here are some best practices for error handling:

• Check the HTTP status code of the response to determine the general category of the error.
• Read the error field of the JSON response body to understand the specific cause of the error.
• Retry a 500 after a short wait: a failed request is not charged. Do not retry a 400, 401, or 413 unchanged: fix the request, the API key, or your credit balance first.
• Display user-friendly error messages to your users based on the error message received.
• Implement appropriate error logging and monitoring mechanisms to track and investigate errors.
• If you encounter persistent or unexpected errors, reach out to our support team for further assistance.

Next Steps

• Review the API Documentation to understand the requirements and constraints of each endpoint.
• Implement robust error handling in your application to provide a smooth user experience.
• If you need further assistance or have questions about error codes, contact our support team.

By understanding and handling error codes and messages effectively, you can build reliable and resilient applications that integrate seamlessly with the ForVoyez API.