Error Handling

Status Code	Description	Handling Recommendation
400	Bad Request	Check your request parameters and ensure they meet the requirements
401	Unauthorized	Verify your API key is valid and properly included in the request
404	Not Found	Confirm the video_id is correct and hasn't expired
413	Payload Too Large	Reduce file size or contact sales for increased limits
429	Too Many Requests	Implement exponential backoff or reduce request frequency
500	Internal Server Error	Retry with exponential backoff; contact support if persistent
503	Service Unavailable	Temporary server overload; retry with exponential backoff

When an API request results in an error (typically HTTP status codes 4xx or 5xx), the response body will be a JSON object containing more details:

{
  "error": "Error type",
  "message": "Detailed error message",
  "request_id": "Request identifier for troubleshooting"
}

Fields:

error: A short string indicating the general type of error (e.g., invalid_parameter, authentication_failed, server_error).
message: A human-readable message providing more specific details about the error.
request_id: A unique ID for the request. Please include this ID when contacting support about a specific API issue.

Implement Exponential Backoff: For transient errors like 429 Too Many Requests, 500 Internal Server Error, or 503 Service Unavailable, implement a retry mechanism with exponential backoff. This means waiting for progressively longer periods between retries (e.g., 1s, 2s, 4s, 8s...). Avoid retrying indefinitely.
Log request_id: For all errors, especially those you report to support, log the request_id from the error response. This helps us quickly locate the specific transaction and diagnose the issue.
Validate Inputs: Before submitting data to the API, validate inputs on your end where possible (e.g., checking for required fields, correct data types). This can prevent many 400 Bad Request errors.
Handle Timeouts: Set reasonable timeouts for your API requests. If a request times out, treat it as a potential transient error and consider a retry (with backoff).
Graceful Degradation: Design your application to handle API unavailability or errors gracefully. For example, if a feature relies on an API call that fails, inform the user appropriately rather than letting the application crash.