Errors

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

Error Response Format

JSON

{
  "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

400 Bad Request

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

Invalid search_type

400 Bad Request

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

Invalid API key

401 Unauthorized

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

Out of credits

402 Payment Required

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

Rate limited

429 Too Many Requests

{
  "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