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" } }
Machine-readable error code (uppercase with underscores)
Human-readable error description
Additional context and debugging information
Unique request identifier for support inquiries
HTTP Status Codes
Errors caused by invalid client requests Invalid request parameters, body, or format
Missing, invalid, or expired authentication token
Valid authentication but insufficient permissions
Requested resource does not exist
Resource already exists or conflicting state
Valid request format but semantic errors
Errors caused by server-side issues 500 Internal Server Error
Unexpected server error
Service temporarily unavailable (maintenance)
Error Codes Reference Authentication Errors No authentication token provided { "code" : "MISSING_TOKEN" , "message" : "Authentication token is required" , "details" : { "hint" : "Include 'Authorization: Bearer <token>' header" } }
Token is malformed or invalid { "code" : "INVALID_TOKEN" , "message" : "Authentication token is invalid" , "details" : { "reason" : "Invalid signature" } }
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" } }
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 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" } ] } }
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" } }
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 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 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 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 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 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
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 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" } }
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 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-ai.vercel.app/checkout/premium-server" } }
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 Unexpected server error { "code" : "INTERNAL_ERROR" , "message" : "An unexpected error occurred" , "details" : { "requestId" : "req_abc123def456" , "hint" : "Contact support with this request ID" } }
Service temporarily unavailable { "code" : "SERVICE_UNAVAILABLE" , "message" : "Service is temporarily unavailable" , "details" : { "reason" : "Scheduled maintenance" , "estimatedResolution" : "2025-12-09T12:00:00Z" , "hint" : "Check https://status.superbox.ai for updates" } }
Error Handling Best Practices 1. Always Check Response Status JavaScript 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 JavaScript 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 JavaScript 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 ; }
JavaScript 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 JavaScript 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
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 backoffError Handling with SDKs Our official SDKs handle errors automatically:
Python SDK from superbox import SuperBoxClient, APIError, RateLimitError client = SuperBoxClient( token = os.getenv( 'SUPERBOX_API_TOKEN' )) try : server = client.servers.create({ 'name' : 'my-server' , 'version' : '1.0.0' , # ... }) except RateLimitError as e: print ( f "Rate limited. Retry after { e.retry_after } s" ) except APIError as e: print ( f "API Error [ { e.code } ]: { e.message } " ) print ( f "Details: { e.details } " )
Support If you encounter an error you can’t resolve:
With proper error handling, your integration will be robust and user-friendly!