Documentation

Error Reference

Common error codes, causes, and solutions for the Veedeo API.

Common Error Codes

Authentication Errors

INVALID_API_KEY

HTTP Status: 401 Unauthorized Cause: The provided API key is invalid or expired Solution: Check your API key in the dashboard and ensure it's correctly formatted

MISSING_AUTHENTICATION

HTTP Status: 401 Unauthorized Cause: Authorization header is missing Solution: Add Authorization: Bearer your_api_key header

INSUFFICIENT_PERMISSIONS

HTTP Status: 403 Forbidden Cause: API key doesn't have required permissions Solution: Check your account tier and permissions

Validation Errors

VALIDATION_ERROR

HTTP Status: 422 Unprocessable Entity Cause: Request format is invalid Solution: Check request body against API specification

MEDIA_DOWNLOAD_FAILED

HTTP Status: 422 Unprocessable Entity Cause: Unable to download media files Solution: Ensure URLs are publicly accessible Retry: Yes

INVALID_MEDIA_FORMAT

HTTP Status: 422 Unprocessable Entity Cause: Unsupported media format Solution: Use supported formats (jpg, png, mp3, mp4, etc.) Retry: No

Rate Limiting

RATE_LIMIT_EXCEEDED

HTTP Status: 429 Too Many Requests Cause: Too many requests in time window Solution: Implement exponential backoff or upgrade tier Retry: Yes (after backoff)

Resource Errors

INSUFFICIENT_CREDITS

HTTP Status: 402 Payment Required Cause: Account has insufficient credits Solution: Add credits to your account Retry: No

QUOTA_EXCEEDED

HTTP Status: 429 Too Many Requests Cause: Monthly quota exceeded Solution: Upgrade your plan or wait for quota reset Retry: No

Processing Errors

PROCESSING_TIMEOUT

HTTP Status: 500 Internal Server Error Cause: Render took longer than maximum allowed time Solution: Simplify timeline or try again Retry: Yes

FILE_TOO_LARGE

HTTP Status: 413 Payload Too Large Cause: Media file exceeds size limits Solution: Compress files or use smaller media Retry: No

TIMELINE_TOO_COMPLEX

HTTP Status: 422 Unprocessable Entity Cause: Timeline exceeds complexity limits Solution: Reduce number of tracks/clips or effects Retry: No

Error Response Format

All errors follow this consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {
      "field": "specific field that caused error",
      "provided_value": "the value that was invalid"
    },
    "request_id": "req_xyz123",
    "documentation_url": "https://docs.veedeo.dev/errors/ERROR_CODE",
    "suggested_action": "What to do next"
  }
}

Handling Errors

Retry Strategy

Implement exponential backoff for retryable errors:

async function retryRequest(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (!isRetryable(error) || attempt === maxRetries - 1) {
        throw error;
      }

      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

function isRetryable(error) {
  const retryableCodes = [
    'RATE_LIMIT_EXCEEDED',
    'PROCESSING_TIMEOUT',
    'MEDIA_DOWNLOAD_FAILED'
  ];
  return retryableCodes.includes(error.code);
}

Logging Errors

Always log the request_id for debugging:

try {
  const response = await fetch('/v3/tasks', options);
} catch (error) {
  console.error('Request failed:', {
    requestId: error.request_id,
    code: error.code,
    message: error.message
  });
}

Getting Help

For detailed error information, see the full Error Reference documentation.

Need support? Contact us: