Skip to main content

​
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"
  }
}
​
success
boolean
Always false for errors
​
error.code
string
Machine-readable error code (uppercase with underscores)
​
error.message
string
Human-readable error description
​
error.details
object
Additional context and debugging information
​
meta.requestId
string
Unique request identifier for support inquiries

​
HTTP Status Codes

Errors caused by invalid client requests
​
400 Bad Request
error
Invalid request parameters, body, or format
​
401 Unauthorized
error
Missing, invalid, or expired authentication token
​
403 Forbidden
error
Valid authentication but insufficient permissions
​
404 Not Found
error
Requested resource does not exist
​
409 Conflict
error
Resource already exists or conflicting state
​
422 Unprocessable Entity
error
Valid request format but semantic errors
​
429 Too Many Requests
error
Rate limit exceeded
Errors caused by server-side issues
​
500 Internal Server Error
error
Unexpected server error
​
502 Bad Gateway
error
Upstream service error
​
503 Service Unavailable
error
Service temporarily unavailable (maintenance)
​
504 Gateway Timeout
error
Upstream service timeout

​
Error Codes Reference

​
Authentication Errors

​
MISSING_TOKEN
401
No authentication token provided
{
"code": "MISSING_TOKEN",
"message": "Authentication token is required",
"details": {
"hint": "Include 'Authorization: Bearer <token>' header"
}
}
​
INVALID_TOKEN
401
Token is malformed or invalid
{
"code": "INVALID_TOKEN",
"message": "Authentication token is invalid",
"details": {
"reason": "Invalid signature"
}
}
​
EXPIRED_TOKEN
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"
}
}
​
FORBIDDEN
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

​
VALIDATION_ERROR
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"
}
]
}
}
​
MISSING_REQUIRED_FIELD
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"
}
}
​
INVALID_FIELD_FORMAT
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

​
RESOURCE_NOT_FOUND
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"
}
}
​
RESOURCE_ALREADY_EXISTS
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"
}
}
​
RESOURCE_CONFLICT
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

​
RATE_LIMIT_EXCEEDED
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

​
REPOSITORY_UNREACHABLE
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"
}
}
​
REPOSITORY_INVALID_STRUCTURE
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

​
SECURITY_SCAN_FAILED
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"
}
}
​
SECRETS_DETECTED
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

​
PAYMENT_REQUIRED
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"
}
}
​
PAYMENT_FAILED
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

​
INTERNAL_ERROR
500
Unexpected server error
{
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred",
"details": {
"requestId": "req_abc123def456",
"hint": "Contact support with this request ID"
}
}
​
SERVICE_UNAVAILABLE
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();

​
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;
 }
  }
}

​
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;
}

​
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);
  }
}

​
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;
  }
}

​
Common Error Scenarios

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
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
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
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!