Errors

The Scavio API uses standard HTTP status codes and returns a structured JSON error body so you can debug issues quickly.

Error Response Format

Every error response has a top-level error string. Validation errors (400) also include a details array that pinpoints each invalid field.

{
  "error": "Human-readable error description"
}

Status Codes

Common Errors

Missing or invalid parameter

{
  "error": "Invalid request: query is required",
  "details": [
    { "path": "query", "message": "query is required" }
  ]
}

Invalid API key

{
  "error": "Invalid or missing API key"
}

Out of credits

{
  "error": "No credits remaining. Please upgrade your plan or purchase additional credits."
}

Wrong HTTP method

{
  "error": "Method GET not allowed on /api/v1/tiktok/video. Use POST with a JSON body.",
  "allowed_methods": ["POST"]
}

Rate limited

{
  "error": "Rate limit exceeded. Retry after 30 seconds."
}

Best Practices

• Always check the HTTP status code before parsing the response body
• Read the error string for a human-readable description, and switch on the HTTP status code for programmatic handling
• On a 400, inspect the details array to see exactly which field failed validation
• Implement retry logic with exponential backoff for 429 and 500 errors
• Do not retry 400, 401, or 405 errors -- fix the request first