Skip to main content

​
Error Response Format

All API errors follow a consistent JSON structure: 
{
  "error": {
    "code": "invalid_request",
    "message": "The 'model_id' field is required",
    "type": "validation_error",
    "param": "model_id",
    "request_id": "req_abc123xyz"
  }
}
FieldDescription
codeMachine-readable error code
messageHuman-readable description
typeError category
paramThe parameter that caused the error (if applicable)
request_idUnique identifier for debugging

​
HTTP Status Codes

StatusDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable - Temporary outage

​
Error Types

​
Authentication Errors

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked",
    "type": "authentication_error"
  }
}
Common causes:
  • API key is malformed or incorrect
  • Key has been revoked
  • Key doesn’t have required scopes

​
Validation Errors

{
  "error": {
    "code": "invalid_request",
    "message": "The 'metrics' field must contain at least one valid metric",
    "type": "validation_error",
    "param": "metrics"
  }
}
Common causes:
  • Missing required fields
  • Invalid field values or types
  • Array/object constraints violated

​
Rate Limit Errors

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "type": "rate_limit_error"
  }
}
The response includes headers to help you handle rate limits: 
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706780400
Retry-After: 30

​
Resource Errors

{
  "error": {
    "code": "model_not_found",
    "message": "No model found with ID 'loan-model-v3'",
    "type": "not_found_error",
    "param": "model_id"
  }
}

​
Handling Errors in SDKs

Our SDKs throw typed exceptions that you can catch and handle: 
from rotavision import Rotavision
from rotavision.exceptions import (
    AuthenticationError,
    ValidationError,
    RateLimitError,
    NotFoundError,
    RotavisionError
)

client = Rotavision()

try:
    result = client.vishwas.analyze(model_id="my-model", dataset=data)
except AuthenticationError as e:
    print(f"Check your API key: {e.message}")
except ValidationError as e:
    print(f"Invalid request: {e.message} (param: {e.param})")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError as e:
    print(f"Resource not found: {e.message}")
except RotavisionError as e:
    print(f"API error: {e.message} (request_id: {e.request_id})")

​
Retry Strategy

For transient errors (rate limits, 5xx errors), we recommend exponential backoff:
Python
import time
from rotavision import Rotavision
from rotavision.exceptions import RateLimitError, RotavisionError

def call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(e.retry_after or (2 ** attempt))
        except RotavisionError as e:
            if e.status_code < 500 or attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
Our SDKs include built-in retry logic with configurable settings. Check the SDK documentation for details.

​
Debugging

When contacting support, always include the request_id from the error response: 
Request ID: req_abc123xyz
Error: rate_limit_exceeded
Timestamp: 2026-02-01T10:30:00Z
You can also find request IDs in the X-Request-Id response header for successful requests.