Error Handling

HTTP Status Codes

The StealthGPT API uses standard HTTP status codes to indicate the success or failure of requests:

success

The request was successful and the response contains the expected data.

success

The work runs asynchronously: the async endpoints always answer 202, and /api/stealthify does for a long text that is still running. Poll statusUrl for the result.

error

The request was malformed or contained invalid parameters.

error

Authentication failed, usually due to an invalid or missing API token.

error

Your request cannot be billed. This can happen when you run out of prepaid words and either (a) you haven’t accepted pay-as-you-go terms (legacy accounts), (b) you don’t have an API plan or a saved payment method, (c) your account is past due, or (d) billing is temporarily delayed.

error

You’ve exceeded the rate limits for the API.

error

An error occurred on the server. These are typically temporary.

error

The detector could not score the text. The failed /api/stealthify/detect request costs no words. Try again after a short wait.

Error Response Format

All error responses follow this consistent format:

{
  "message": "Human-readable error message"
}

Some error responses may include additional information:

{
  "message": "Invalid request",
  "info": [
    {
      "code": "invalid_type",
      "expected": "boolean",
      "received": "string",
      "path": ["rephrase"],
      "message": "Expected boolean, received string"
    }
  ]
}

Common Errors and Solutions

Authentication Errors

Invalid API Token

Error: 401 UnauthorizedResponse:

{
  "message": "Unauthorized"
}

Solution: Verify that you’re including the correct API token in the api-token header. Check your StealthGPT dashboard under the “API Key” tab for the correct token.

# Incorrect
--header 'api-token: invalid_token'

# Correct
--header 'api-token: your_valid_token_here'

Missing API Token

Error: 401 UnauthorizedResponse:

{
  "message": "Unauthorized. API token is required."
}

/api/stealthify/balance answers the same way. The other endpoints word it as API token is missing. You can find it here https://www.stealthgpt.ai/api-dashboard.Solution: Ensure you’re including the api-token header in all requests.

# Missing header
curl --location 'https://www.stealthgpt.ai/api/stealthify' \
    --header 'Content-Type: application/json' \
    --data '{ "prompt": "test", "rephrase": false, "model": "super" }'

# Correct
curl --location 'https://www.stealthgpt.ai/api/stealthify' \
    --header 'api-token: YOUR_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{ "prompt": "test", "rephrase": false, "model": "super" }'

Request Errors

Missing Required Parameters

Error: 400 Bad RequestResponse:

{
  "message": "Invalid request",
  "info": [
    {
      "code": "invalid_type",
      "expected": "boolean",
      "received": "undefined",
      "path": ["rephrase"],
      "message": "Required"
    }
  ]
}

Solution: Ensure all required parameters are included in your request. For the /api/stealthify endpoint, prompt, rephrase and model are required.

# Missing rephrase parameter
--data '{ "prompt": "test", "model": "super" }'

# Correct
--data '{ "prompt": "test", "rephrase": false, "model": "super" }'

Invalid Parameter Values

Error: 400 Bad RequestResponse:

{
  "message": "Invalid request",
  "info": [
    {
      "code": "invalid_type",
      "expected": "boolean",
      "received": "string",
      "path": ["rephrase"],
      "message": "Expected boolean, received string"
    }
  ]
}

Solution: Check that parameter values are in the correct format.

# Invalid boolean value (should be true/false, not "true"/"false")
--data '{ "prompt": "test", "rephrase": "false", "model": "super" }'

# Correct
--data '{ "prompt": "test", "rephrase": false, "model": "super" }'

Empty Prompt

Error: 400 Bad RequestResponse:

{
  "message": "Invalid request",
  "info": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "string",
      "inclusive": true,
      "exact": false,
      "path": ["prompt"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

Solution: Ensure the prompt parameter contains non-empty content.

# Empty prompt
--data '{ "prompt": "", "rephrase": false, "model": "super" }'

# Correct
--data '{ "prompt": "Write about renewable energy", "rephrase": false, "model": "super" }'

Word Limit Exceeded

Error: 400 Bad RequestResponse:

{
  "message": "The text exceeds the 3,000 word limit"
}

Solution: Keep your prompt text under 3,000 words.

Not Enough Credits

Error: 402 Payment RequiredResponse:

{
  "message": "Payment required or payment method not set up"
}

Solution:

If you are out of prepaid words, you can:
- Subscribe to an API plan; pay-as-you-go turns on with your first payment, or
- Set up pay-as-you-go billing (saved payment method) and accept the updated pay-as-you-go terms (legacy accounts)

Rate Limit Errors

Too Many Requests

Error: 429 Too Many RequestsSolution: Implement request throttling in your application and avoid making too many requests in a short period.

# Python example with retry logic
import requests
import time

def call_api_with_retry(url, headers, data, max_retries=3, retry_delay=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 429:
            # Wait before retrying
            time.sleep(retry_delay)
            continue
            
        return response
        
    return response  # Return last response if all retries failed

Network and Server Errors

Network Timeout

Error: 504 Gateway TimeoutSolution: Implement timeout handling and retry logic for network issues.

# Python example with timeout handling
import requests
from requests.exceptions import Timeout, ConnectionError

def call_api_with_timeout(prompt, rephrase, timeout=600):
    try:
        response = requests.post(
            'https://www.stealthgpt.ai/api/stealthify',
            headers={
                'api-token': 'YOUR_API_TOKEN',
                'Content-Type': 'application/json'
            },
            json={
                'prompt': prompt,
                'rephrase': rephrase,
                'model': 'super'
            },
            timeout=timeout
        )
        response.raise_for_status()
        return response.json()
    except Timeout:
        print("Request timed out. The server might be experiencing high load.")
        raise
    except ConnectionError:
        print("Network connection error. Please check your internet connection.")
        raise

Server Error

Error: 500 Internal Server ErrorSolution: Implement exponential backoff retry logic for server-side errors.

// Go example with exponential backoff
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

func callAPIWithBackoff(prompt string, rephrase bool) (*http.Response, error) {
    maxRetries := 3
    baseDelay := time.Second

    requestBody, _ := json.Marshal(map[string]interface{}{
        "prompt":   prompt,
        "rephrase": rephrase,
        "model":    "super",
    })

    for i := 0; i < maxRetries; i++ {
        req, _ := http.NewRequest("POST", "https://www.stealthgpt.ai/api/stealthify", 
            bytes.NewBuffer(requestBody))
        
        req.Header.Set("api-token", "YOUR_API_TOKEN")
        req.Header.Set("Content-Type", "application/json")

        resp, err := http.DefaultClient.Do(req)
        if err != nil {
            return nil, err
        }

        if resp.StatusCode != 500 {
            return resp, nil
        }

        // Exponential backoff
        delay := baseDelay * time.Duration(1<<uint(i))
        time.Sleep(delay)
    }

    return nil, fmt.Errorf("max retries exceeded")
}

Language-Specific Error Handling Examples

Here are comprehensive error handling examples in different programming languages:

import requests
from requests.exceptions import RequestException
import time
import uuid

class StealthGPTError(Exception):
    """Custom exception for StealthGPT API errors"""
    pass

def call_stealthgpt_api(prompt, rephrase, max_retries=3):
    headers = {
        'api-token': 'YOUR_API_TOKEN',
        'Content-Type': 'application/json',
        # One key per call, resent on retries, so a long text's run is billed once
        'idempotency-key': str(uuid.uuid4())
    }
    data = {
        'prompt': prompt,
        'rephrase': rephrase,
        'model': 'super'
    }

    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://www.stealthgpt.ai/api/stealthify',
                headers=headers,
                json=data,
                timeout=600
            )
            
            # 202: a long text is still running as a run, so poll its statusUrl
            if response.status_code in (200, 202):
                return response.json()
            
            error_data = response.json()
            error_message = error_data.get('message', 'Unknown error')
                
            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                time.sleep(retry_after)
                continue
                
            if response.status_code == 400:
                raise StealthGPTError(f"Invalid request: {error_message}")
                
            if response.status_code == 401:
                raise StealthGPTError("Unauthorized: Invalid API token")
            
            if response.status_code == 402:
                raise StealthGPTError(f"Payment required: {error_message}")
                
            response.raise_for_status()
            
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise StealthGPTError("Request timed out after multiple attempts")
            time.sleep(2 ** attempt)  # Exponential backoff
            
        except requests.exceptions.RequestException as e:
            raise StealthGPTError(f"Request failed: {str(e)}")
            
    raise StealthGPTError("Max retries exceeded")

class StealthGPTClient {
  constructor(apiToken) {
    this.apiToken = apiToken;
    this.baseURL = 'https://www.stealthgpt.ai/api';
    this.maxRetries = 3;
  }

  async stealthify(prompt, rephrase) {
    let lastError;
    // One key per call, resent on retries, so a long text's run is billed once
    const idempotencyKey = crypto.randomUUID();
    
    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        const response = await fetch(`${this.baseURL}/stealthify`, {
          method: 'POST',
          headers: {
            'api-token': this.apiToken,
            'Content-Type': 'application/json',
            'idempotency-key': idempotencyKey,
          },
          body: JSON.stringify({ prompt, rephrase, model: 'super' }),
        });

        if (!response.ok) {
          const errorData = await response.json();
          const errorMessage = errorData.message || 'Unknown error';
          
          switch (response.status) {
            case 400:
              throw new Error(`Invalid request: ${errorMessage}`);
            case 401:
              throw new Error('Unauthorized: Invalid API token');
            case 402:
              throw new Error(`Payment required: ${errorMessage}`);
            case 429:
              const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
              await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
              continue;
            default:
              throw new Error(`API error: ${errorMessage}`);
          }
        }

        return await response.json();
        
      } catch (error) {
        lastError = error;
        
        if (error.message.includes('Invalid') || 
            error.message.includes('Unauthorized') || 
            error.message.includes('Payment required')) {
          throw error; // Don't retry client errors
        }
        
        // Exponential backoff for other errors
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
      }
    }

    throw lastError || new Error('Max retries exceeded');
  }
}

Best Practices for Error Handling

Implement Retry Logic: For transient errors (like 429 or 500), implement retry logic with exponential backoff.
Validate Inputs: Validate all parameters before sending requests to avoid 400 errors.
Check Response Status: Always check the HTTP status code before trying to process the response.
Error Logging: Log detailed error information for troubleshooting.
Handle Errors Gracefully: Provide user-friendly error messages in your application rather than exposing raw API errors.

// Node.js example of comprehensive error handling
async function callStealthGPT(prompt, rephrase) {
  try {
    const response = await axios.post('https://www.stealthgpt.ai/api/stealthify', {
      prompt,
      rephrase,
      model: 'super'
    }, {
      headers: {
        'api-token': process.env.API_TOKEN,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    // Handle different error types
    if (error.response) {
      // The request was made and server responded with an error code
      const errorMessage = error.response.data.message || 'Unknown error';
      
      switch (error.response.status) {
        case 400:
          console.error('Invalid request parameters:', error.response.data);
          throw new Error(`Invalid request: ${errorMessage}`);
        case 401:
          console.error('Authentication failed');
          throw new Error('API authentication failed. Please check your API token.');
        case 402:
          console.error('Payment required');
          throw new Error(`Payment required: ${errorMessage}`);
        case 429:
          console.error('Rate limit exceeded');
          throw new Error('Too many requests. Please try again later.');
        default:
          console.error(`Error ${error.response.status}:`, error.response.data);
          throw new Error('An error occurred while processing your request.');
      }
    } else if (error.request) {
      // The request was made but no response received
      console.error('No response received:', error.request);
      throw new Error('No response from server. Please check your connection.');
    } else {
      // Something else caused the error
      console.error('Error setting up request:', error.message);
      throw new Error('Failed to send request.');
    }
  }
} 

Getting Started

Endpoints

Stealth Agent

Recipes

Integrations

Resources

HTTP Status Codes

Error Response Format

Common Errors and Solutions

Authentication Errors

Request Errors

Rate Limit Errors

Network and Server Errors

Language-Specific Error Handling Examples

Best Practices for Error Handling

​HTTP Status Codes

​Error Response Format

​Common Errors and Solutions

​Authentication Errors

​Request Errors

​Rate Limit Errors

​Network and Server Errors

​Language-Specific Error Handling Examples

​Best Practices for Error Handling

HTTP Status Codes

Error Response Format

Common Errors and Solutions

Authentication Errors

Request Errors

Rate Limit Errors

Network and Server Errors

Language-Specific Error Handling Examples

Best Practices for Error Handling