Error Handling

Error Response Format

All error responses from the SuperBox API follow a consistent structure:

{
  "success": false,
  "error": {
 "code": "ERROR_CODE",
 "message": "Human-readable error message",
 "details": {
"field": "specific_field",
"reason": "Additional context",
"hint": "Suggestion to fix the error"
 }
  },
  "meta": {
 "timestamp": "2025-12-09T10:30:00Z",
 "version": "v1",
 "requestId": "req_abc123def456"
  }
}

boolean

Always false for errors

string

Machine-readable error code (uppercase with underscores)

string

Human-readable error description

object

Additional context and debugging information

string

Unique request identifier for support inquiries

HTTP Status Codes

4xx Client Errors

Errors caused by invalid client requests

error

Invalid request parameters, body, or format

error

Missing, invalid, or expired authentication token

error

Valid authentication but insufficient permissions

error

Requested resource does not exist

error

Resource already exists or conflicting state

error

Valid request format but semantic errors

error

Rate limit exceeded

5xx Server Errors

Errors caused by server-side issues

error

Unexpected server error

error

Upstream service error

error

Service temporarily unavailable (maintenance)

error

Upstream service timeout

Error Codes Reference

Authentication Errors

401

No authentication token provided

{
"code": "MISSING_TOKEN",
"message": "Authentication token is required",
"details": {
"hint": "Include 'Authorization: Bearer <token>' header"
}
}

401

Token is malformed or invalid

{
"code": "INVALID_TOKEN",
"message": "Authentication token is invalid",
"details": {
"reason": "Invalid signature"
}
}

401

Token has expired

{
"code": "EXPIRED_TOKEN",
"message": "Authentication token has expired",
"details": {
"expiredAt": "2025-12-09T10:30:00Z",
"hint": "Refresh your token and try again"
}
}

403

Insufficient permissions for the requested action

{
"code": "FORBIDDEN",
"message": "You don't have permission to perform this action",
"details": {
"required": "owner",
"current": "user",
"resource": "server:weather-mcp"
}
}

Validation Errors

400

Request validation failed

{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": {
"errors": [
{
"field": "name",
"message": "Server name must be lowercase with hyphens",
"value": "MyServer123"
},
{
"field": "version",
"message": "Version must follow semver format",
"value": "1.0"
}
]
}
}

400

Required field is missing

{
"code": "MISSING_REQUIRED_FIELD",
"message": "Required field is missing",
"details": {
"field": "entrypoint",
"hint": "Specify the entry point file for your server"
}
}

400

Field format is invalid

{
"code": "INVALID_FIELD_FORMAT",
"message": "Field format is invalid",
"details": {
"field": "repository.url",
"expected": "Valid Git repository URL",
"received": "not-a-url"
}
}

Resource Errors

404

Requested resource doesn’t exist

{
"code": "RESOURCE_NOT_FOUND",
"message": "Server not found",
"details": {
"resource": "server",
"identifier": "non-existent-server",
"hint": "Check the server name and try again"
}
}

409

Resource with the same identifier already exists

{
"code": "RESOURCE_ALREADY_EXISTS",
"message": "Server with this name already exists",
"details": {
"resource": "server",
"name": "weather-mcp",
"existingVersion": "1.2.0",
"hint": "Choose a different name or update the existing server"
}
}

409

Resource is in a conflicting state

{
"code": "RESOURCE_CONFLICT",
"message": "Cannot delete server while it's being executed",
"details": {
"resource": "server",
"name": "weather-mcp",
"state": "executing",
"hint": "Wait for execution to complete or cancel it first"
}
}

Rate Limiting Errors

429

API rate limit exceeded

{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"details": {
"limit": 1000,
"remaining": 0,
"resetAt": "2025-12-09T11:00:00Z",
"retryAfter": 300,
"hint": "Wait 5 minutes before making more requests"
}
}

Check X-RateLimit-* headers for rate limit information

Repository Errors

422

Cannot access the Git repository

{
"code": "REPOSITORY_UNREACHABLE",
"message": "Unable to access Git repository",
"details": {
"url": "https://github.com/user/repo",
"reason": "Repository is private or doesn't exist",
"hint": "Ensure the repository is public and URL is correct"
}
}

422

Repository doesn’t have valid MCP server structure

{
"code": "REPOSITORY_INVALID_STRUCTURE",
"message": "Repository doesn't contain a valid MCP server",
"details": {
"missingFiles": ["main.py", "requirements.txt"],
"hint": "Ensure your repository has all required files"
}
}

Security Errors

422

Security scan found critical issues

{
"code": "SECURITY_SCAN_FAILED",
"message": "Security scan detected critical vulnerabilities",
"details": {
"criticalIssues": 3,
"scanners": ["sonarcloud", "gitguardian", "bandit"],
"report": "/api/v1/servers/server-name/security-report",
"hint": "Fix security issues and resubmit"
}
}

422

Secret keys or credentials found in code

{
"code": "SECRETS_DETECTED",
"message": "Secret keys detected in repository",
"details": {
"secretsFound": 2,
"types": ["API Key", "AWS Access Key"],
"hint": "Remove all secrets from your code and use environment variables"
}
}

Payment Errors

402

Payment required to access this server

{
"code": "PAYMENT_REQUIRED",
"message": "This server requires payment",
"details": {
"server": "premium-server",
"price": {
"amount": 9.99,
"currency": "USD"
},
"paymentUrl": "https://superbox.1mindlabs.org/checkout/premium-server"
}
}

422

Payment processing failed

{
"code": "PAYMENT_FAILED",
"message": "Payment processing failed",
"details": {
"reason": "Insufficient funds",
"provider": "razorpay",
"hint": "Check your payment method and try again"
}
}

Server Errors

500

Unexpected server error

{
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred",
"details": {
"requestId": "req_abc123def456",
"hint": "Contact support with this request ID"
}
}

503

Service temporarily unavailable

{
"code": "SERVICE_UNAVAILABLE",
"message": "Service is temporarily unavailable",
"details": {
"reason": "Scheduled maintenance",
"estimatedResolution": "2025-12-09T12:00:00Z",
"hint": "Check https://github.com/areebahmeddd/SuperBox-FE/issues for updates"
}
}

Error Handling Best Practices

1. Always Check Response Status

const response = await fetch('https://api.superbox.ai/api/v1/servers');

if (!response.ok) {
const error = await response.json();
console.error(`Error ${response.status}:`, error.error.message);
// Handle error based on status code
}

const data = await response.json();

response = requests.get('https://api.superbox.ai/api/v1/servers')

if not response.ok:
 error = response.json()
 print(f"Error {response.status_code}: {error['error']['message']}")
 # Handle error based on status code
else:
 data = response.json()

resp, err := http.Get("https://api.superbox.ai/api/v1/servers")
if err != nil {
 log.Fatal(err)
}
defer resp.Body.Close()

if resp.StatusCode != http.StatusOK {
 var errorResp ErrorResponse
 json.NewDecoder(resp.Body).Decode(&errorResp)
 log.Printf("Error %d: %s", resp.StatusCode, errorResp.Error.Message)
 // Handle error based on status code
}

2. Implement Retry Logic

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
 try {
const response = await fetch(url, options);

// Don't retry on client errors (4xx)
if (response.status >= 400 && response.status < 500) {
  return response;
}

// Retry on server errors (5xx) or network issues
if (response.ok) {
  return response;
}

// Exponential backoff
await new Promise(resolve => 
  setTimeout(resolve, Math.pow(2, i) * 1000)
);
 } catch (error) {
if (i === maxRetries - 1) throw error;
 }
  }
}

import time
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_session_with_retry():
 session = requests.Session()
 retry = Retry(
  total=3,
  backoff_factor=1,
  status_forcelist=[500, 502, 503, 504],
  allowed_methods=["GET", "POST", "PUT", "DELETE"]
 )
 adapter = HTTPAdapter(max_retries=retry)
 session.mount('http://', adapter)
 session.mount('https://', adapter)
 return session

session = create_session_with_retry()
response = session.get('https://api.superbox.ai/api/v1/servers')

3. Handle Rate Limiting

async function fetchWithRateLimit(url, options = {}) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
 const resetTime = response.headers.get('X-RateLimit-Reset');
 const waitTime = (parseInt(resetTime) * 1000) - Date.now();
 
 console.log(`Rate limited. Waiting ${waitTime}ms...`);
 await new Promise(resolve => setTimeout(resolve, waitTime));
 
 // Retry the request
 return fetchWithRateLimit(url, options);
  }
  
  return response;
}

import time

def request_with_rate_limit(url, headers):
 response = requests.get(url, headers=headers)

 if response.status_code == 429:
  reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
  wait_time = reset_time - int(time.time())

  if wait_time > 0:
print(f"Rate limited. Waiting {wait_time}s...")
time.sleep(wait_time)
return request_with_rate_limit(url, headers)

 return response

4. Validate Input Before Sending

function validateServerData(data) {
  const errors = [];
  
  // Name validation
  if (!/^[a-z0-9-]+$/.test(data.name)) {
 errors.push({
field: 'name',
message: 'Name must be lowercase with hyphens only'
 });
  }
  
  // Version validation
  if (!/^\d+\.\d+\.\d+$/.test(data.version)) {
 errors.push({
field: 'version',
message: 'Version must follow semver format (x.y.z)'
 });
  }
  
  // Repository URL validation
  const urlPattern = /^https:\/\/github\.com\/[\w-]+\/[\w-]+$/;
  if (!urlPattern.test(data.repository?.url)) {
 errors.push({
field: 'repository.url',
message: 'Must be a valid GitHub repository URL'
 });
  }
  
  if (errors.length > 0) {
 throw new ValidationError('Validation failed', errors);
  }
}

import re

def validate_server_data(data):
 errors = []

 # Name validation
 if not re.match(r'^[a-z0-9-]+$', data['name']):
  errors.append({
'field': 'name',
'message': 'Name must be lowercase with hyphens only'
  })

 # Version validation
 if not re.match(r'^\d+\.\d+\.\d+$', data['version']):
  errors.append({
'field': 'version',
'message': 'Version must follow semver format (x.y.z)'
  })

 # Repository URL validation
 url_pattern = r'^https://github\.com/[\w-]+/[\w-]+$'
 if not re.match(url_pattern, data.get('repository', {}).get('url', '')):
  errors.append({
'field': 'repository.url',
'message': 'Must be a valid GitHub repository URL'
  })

 if errors:
  raise ValidationError('Validation failed', errors)

5. Log Errors for Debugging

async function makeRequest(url, options = {}) {
  try {
 const response = await fetch(url, options);
 
 if (!response.ok) {
const error = await response.json();

// Log detailed error information
console.error({
  timestamp: new Date().toISOString(),
  url,
  method: options.method || 'GET',
  status: response.status,
  requestId: error.meta?.requestId,
  errorCode: error.error?.code,
  message: error.error?.message,
  details: error.error?.details
});

throw new APIError(error);
 }
 
 return response.json();
  } catch (error) {
 console.error('Request failed:', error);
 throw error;
  }
}

import logging
from datetime import datetime

logger = logging.getLogger(__name__)

def make_request(url, **kwargs):
 try:
  response = requests.request(url=url, **kwargs)

  if not response.ok:
error = response.json()

# Log detailed error information
logger.error({
 'timestamp': datetime.utcnow().isoformat(),
 'url': url,
 'method': kwargs.get('method', 'GET'),
 'status': response.status_code,
 'request_id': error.get('meta', {}).get('requestId'),
 'error_code': error.get('error', {}).get('code'),
 'message': error.get('error', {}).get('message'),
 'details': error.get('error', {}).get('details')
})

raise APIError(error)

  return response.json()
 except Exception as e:
  logger.exception('Request failed')
  raise

Common Error Scenarios

Scenario 1: Creating a Server with Invalid Name

Request:

curl -X POST "https://api.superbox.ai/api/v1/servers" \
-H "Authorization: Bearer $TOKEN" \
-d '{"name": "My Server!", "version": "1.0.0", ...}'

Response: 400 Bad Request

{
"success": false,
"error": {
 "code": "VALIDATION_ERROR",
 "message": "Server name contains invalid characters",
 "details": {
"field": "name",
"value": "My Server!",
"hint": "Use lowercase letters, numbers, and hyphens only"
 }
}
}

Solution: Use a valid name: my-server

Scenario 2: Token Expired During Request

Request:

curl -X GET "https://api.superbox.ai/api/v1/servers" \
-H "Authorization: Bearer expired_token"

Response: 401 Unauthorized

{
"success": false,
"error": {
 "code": "EXPIRED_TOKEN",
 "message": "Authentication token has expired"
}
}

Solution: Refresh your Firebase token and retry

Scenario 3: Deleting Someone Else's Server

Request:

curl -X DELETE "https://api.superbox.ai/api/v1/servers/other-user-server" \
-H "Authorization: Bearer $TOKEN"

Response: 403 Forbidden

{
"success": false,
"error": {
 "code": "FORBIDDEN",
 "message": "You don't have permission to delete this server",
 "details": {
"owner": "other-user",
"requester": "you"
 }
}
}

Solution: You can only delete servers you own

Scenario 4: Rate Limit Exceeded

Request:

# After 1000 requests in an hour
curl -X GET "https://api.superbox.ai/api/v1/servers"

Response: 429 Too Many Requests

{
"success": false,
"error": {
 "code": "RATE_LIMIT_EXCEEDED",
 "message": "Rate limit exceeded",
 "details": {
"resetAt": "2025-12-09T11:00:00Z",
"retryAfter": 300
 }
}
}

Solution: Wait for rate limit reset or implement exponential backoff

Support

If you encounter an error you can’t resolve:

Contact Support

Include your error details for faster resolution

GitHub Issues

Report bugs or request features

With proper error handling, your integration will be robust and user-friendly!

Getting Started

Core Concepts

Infrastructure

Backend

Frontend

REST API

Servers API

Auth API

CLI

CLI Commands

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting Errors

Repository Errors

Security Errors

Payment Errors

Server Errors

Error Handling Best Practices

1. Always Check Response Status

2. Implement Retry Logic

3. Handle Rate Limiting

4. Validate Input Before Sending

5. Log Errors for Debugging

Common Error Scenarios

Support

Contact Support

GitHub Issues

​Error Response Format

​HTTP Status Codes

​Error Codes Reference

​Authentication Errors

​Validation Errors

​Resource Errors

​Rate Limiting Errors

​Repository Errors

​Security Errors

​Payment Errors

​Server Errors

​Error Handling Best Practices

​1. Always Check Response Status

​2. Implement Retry Logic

​3. Handle Rate Limiting

​4. Validate Input Before Sending

​5. Log Errors for Debugging

​Common Error Scenarios

​Support

Contact Support

GitHub Issues

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting Errors

Repository Errors

Security Errors

Payment Errors

Server Errors

Error Handling Best Practices

1. Always Check Response Status

2. Implement Retry Logic

3. Handle Rate Limiting

4. Validate Input Before Sending

5. Log Errors for Debugging

Common Error Scenarios

Support