Errors

The Scavio API uses standard HTTP status codes and returns structured error responses to help you debug issues quickly.

Error Response Format

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable error description"
  }
}

Status Codes

Status	Code	Description
400	`bad_request`	Invalid request body or missing required parameters
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key does not have permission for this action
402	`insufficient_credits`	No credits remaining. Top up or upgrade your plan.
429	`rate_limit_exceeded`	Too many requests. Wait and retry.
500	`internal_error`	Server error. Retry after a short delay.

Common Errors

Missing query parameter

// Status: 400
{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

Invalid API key

// Status: 401
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Out of credits

// Status: 402
{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

Rate limited

// Status: 429
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

Best Practices

Always check the HTTP status code before parsing the response body
Use the error.code field for programmatic error handling
Use the error.message field for logging and debugging
Implement retry logic with exponential backoff for 429 and 500 errors
Do not retry 400 or 401 errors -- fix the request first