Error Codes

When a request to the Valossa Core API fails, the response includes a non-200 HTTP status code and a JSON body containing error details.

Error Response Format

All error responses follow this JSON structure:

{
  "errors": [
    {
      "message": "Description of the error"
    }
  ]
}

The errors array contains one or more error objects, each with a message field describing what went wrong.

HTTP Status Codes

Status Code	Meaning
200	Success. The request was processed correctly.
400	Bad Request. The request is malformed, missing required fields, or contains invalid values.
401	Unauthorized. The API key is invalid, missing, or does not have permission for the requested operation.
404	Not Found. The specified job_id does not exist or is not accessible with the provided API key.
500	Internal Server Error. An unexpected error occurred on the server side.

Common Errors

Invalid API Key

{
  "errors": [
    {
      "message": "Invalid API key"
    }
  ]
}

Cause: The api_key value is incorrect, expired, or not recognized.

Solution: Verify your API key in Valossa Portal under "My Account" > "Subscriptions and API Keys".

Missing Required Fields

{
  "errors": [
    {
      "message": "Missing required field: media.video.url"
    }
  ]
}

Cause: A required field is absent from the request body.

Solution: Check the endpoint documentation for required fields and ensure your JSON is correctly formatted.

Malformed JSON

{
  "errors": [
    {
      "message": "Malformed request body"
    }
  ]
}

Cause: The request body is not valid JSON.

Solution: Validate your JSON syntax. Ensure Content-Type: application/json is set in the request headers for POST requests.

Job Not Found

{
  "errors": [
    {
      "message": "Job not found"
    }
  ]
}

Cause: The job_id does not exist or is not associated with the provided API key.

Solution: Verify the job_id value. Ensure you are using the same API key that was used to create the job.

Job Not Finished

Attempting to download results for a job that is still processing may return an error.

Solution: Poll job_status and wait for the finished status before calling job_results.

Distinguishing Errors from Successes

Error responses can be identified by:

1. HTTP status code: Any non-200 response code indicates an error.
2. JSON structure: Error responses always contain an errors array at the top level.

Successful responses always return HTTP 200 and do not contain an errors array.

Handling Errors in Code

Python

import requests

response = requests.post(
    "https://api-eu.valossa.com/core/1.0/new_job",
    json={"api_key": "YOUR_API_KEY", "media": {"video": {"url": "https://example.com/video.mp4"}}}
)

if response.status_code != 200:
    errors = response.json().get("errors", [])
    for error in errors:
        print(f"Error: {error['message']}")
else:
    result = response.json()
    print(f"Job created: {result['job_id']}")

JavaScript

const response = await fetch("https://api-eu.valossa.com/core/1.0/new_job", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    media: { video: { url: "https://example.com/video.mp4" } }
  })
});

if (!response.ok) {
  const errorData = await response.json();
  errorData.errors.forEach(err => console.error("Error:", err.message));
} else {
  const result = await response.json();
  console.log("Job created:", result.job_id);
}

Notes

• Error responses described here pertain to immediate HTTP responses to API calls (malformed requests, invalid keys, etc.).
• Errors that occur during asynchronous processing (e.g., the video URL is unreachable) are reflected in the job status rather than in the HTTP response to the new_job call.