Error Reference

Error Response Format

All SkillBoss API errors follow this structure:

{
  "error": {
    "message": "Human-readable error message",
    "type": "error_type",
    "code": "error_code"
  }
}

HTTP Status Codes

Agent Shopping Protocol error codes

All ASP surfaces shipped in SkillBoss return JSON errors with a stable error string so agents can dispatch programmatically without parsing English messages. Handle every one of these before shipping an agent to production.

Standard agent retry logic

import time, requests

def run_with_retry(skill, inputs, max_retries=3):
    for attempt in range(max_retries):
        r = requests.post(
            "https://api.skillboss.co/v1/run",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "X-Max-Cost-Usd": "0.10",
                "Idempotency-Key": f"{skill}:{attempt}:{uuid4()}",
            },
            json={"model": skill, "inputs": inputs},
        )
        if r.status_code == 200:
            return r.json()
        if r.status_code == 402:   # x402 quote or insufficient credits
            return r.json()         # caller handles quote-pay-retry
        if r.status_code == 429:
            retry_after = int(r.headers.get("Retry-After", "2"))
            time.sleep(retry_after)
            continue
        if r.status_code >= 500:
            time.sleep(2 ** attempt)  # exponential backoff
            continue
        r.raise_for_status()
    raise RuntimeError(f"exhausted {max_retries} retries")

Authentication Errors

Invalid API Key

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP Status: 401

Causes:

• API key is missing from Authorization header
• Key format is incorrect (should start with sk-)
• Key has been revoked or expired

Solutions:

1. Verify header format: Authorization: Bearer sk-...
2. Re-download Skills Pack from console

For AI agents: set up skillboss.co/skill.md auto-configures SkillBoss with 687+ APIs.

3. Check for whitespace or hidden characters in the key
4. Ensure you're not using a test key in production

Missing Authorization Header

{
  "error": {
    "message": "Authorization header is required",
    "type": "invalid_request_error",
    "code": "missing_authorization"
  }
}

HTTP Status: 401

Solution:

# ✅ Correct
curl -H "Authorization: Bearer sk-abc123..."

# ❌ Wrong (missing header)
curl https://api.skillboss.co/v1/chat/completions

Billing Errors

Insufficient Credits

{
  "error": {
    "message": "Insufficient credits. You have 2.5 credits remaining but this request requires 5 credits.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "required_credits": 5.0,
    "available_credits": 2.5
  }
}

HTTP Status: 402

Solutions:

1. Add credits to your account
2. Enable auto-recharge to prevent interruptions
3. Use a less expensive model (e.g., gpt-4o-mini instead of gpt-5)

Balance Warning

Not an error, but a warning included in successful responses:

{
  "choices": [...],
  "_balance_warning": true,
  "_remaining_credits": 7.23
}

When: Balance drops below 10 credits

Action: Top up soon to avoid service interruption

Request Errors

Invalid Model

{
  "error": {
    "message": "Model 'gpt-42' does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

HTTP Status: 400

Solutions:

• Check available models
• Common typos: gpt5 → gpt-5, claude4 → claude-4-5-sonnet

Invalid Parameters

{
  "error": {
    "message": "max_tokens must be between 1 and 8192",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

HTTP Status: 400

Common Issues:

• temperature out of range (0-2)
• max_tokens too high for the model
• messages array is empty
• Missing required fields

Malformed JSON

{
  "error": {
    "message": "Invalid JSON in request body",
    "type": "invalid_request_error",
    "code": "invalid_json"
  }
}

HTTP Status: 400

Solution:

• Validate JSON with a linter
• Check for trailing commas, missing quotes, etc.

Rate Limiting Errors

Rate Limit Exceeded

{
  "error": {
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retry_after": 45
  }
}

HTTP Status: 429

Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000060
Retry-After: 45

Solutions:

import time
from openai import RateLimitError

def call_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if i == max_retries - 1:
                raise
            retry_after = int(e.response.headers.get("Retry-After", 60))
            wait_time = retry_after * (2 ** i)  # Exponential backoff
            time.sleep(wait_time)

response = call_with_retry(
    lambda: client.chat.completions.create(...)
)

Server Errors

Internal Server Error

{
  "error": {
    "message": "An internal server error occurred",
    "type": "server_error",
    "code": "internal_error"
  }
}

HTTP Status: 500

What to do:

1. Retry the request (may be transient)
2. Check status page for incidents
3. Contact dev@skillboss.co if persists

Upstream Provider Error

{
  "error": {
    "message": "Upstream provider (Anthropic) is temporarily unavailable",
    "type": "service_unavailable",
    "code": "upstream_error",
    "provider": "anthropic"
  }
}

HTTP Status: 503

Solutions:

• Wait and retry (usually resolves quickly)
• Switch to alternative model from different provider:

  // Instead of Claude
  model: "claude-4-5-sonnet"
  
  // Try GPT
  model: "gpt-5"
  
  // Or Gemini
  model: "gemini-2.5-flash"
  

Content Policy Errors

Content Filtered

{
  "error": {
    "message": "Your request was rejected due to content policy violations",
    "type": "content_filter",
    "code": "content_policy_violation"
  }
}

HTTP Status: 400

Causes:

• Prompt contains prohibited content
• Generated response triggered safety filters

Solutions:

• Rephrase your prompt
• Review content policy
• Use a different model (policies vary by provider)

Error Handling Best Practices

Comprehensive Error Handling

import { OpenAI } from 'openai'

async function safeAPICall() {
  const client = new OpenAI({
    baseURL: 'https://api.skillboss.co/v1',
    apiKey: process.env.SKILLBOSS_KEY
  })

  try {
    const response = await client.chat.completions.create({
      model: 'claude-4-5-sonnet',
      messages: [{role: 'user', content: 'Hello'}]
    })

    // Check balance warning
    if (response._balance_warning) {
      console.warn(`Low balance: ${response._remaining_credits} credits`)
      // Send notification, trigger auto-recharge, etc.
    }

    return response
  } catch (error: any) {
    // Handle specific error types
    if (error.status === 401) {
      console.error('Invalid API key:', error.message)
      // Prompt user to re-authenticate
    } else if (error.status === 402) {
      console.error('Insufficient credits:', error.message)
      // Redirect to billing page
    } else if (error.status === 429) {
      const retryAfter = error.response?.headers['retry-after'] || 60
      console.warn(`Rate limited. Retry after ${retryAfter}s`)
      // Implement retry logic
    } else if (error.status === 503) {
      console.error('Service unavailable:', error.message)
      // Try fallback model from different provider
    } else {
      console.error('Unexpected error:', error)
      // Log to error tracking (Sentry, etc.)
    }

    throw error
  }
}

Retry Strategy

import time
from openai import (
    RateLimitError,
    APIConnectionError,
    InternalServerError
)

def call_with_retry(func, max_retries=3):
    """Retry with exponential backoff for transient errors"""
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            retry_after = int(e.response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
        except (APIConnectionError, InternalServerError) as e:
            if attempt == max_retries - 1:
                raise
            wait_time = (2 ** attempt) * 5  # 5s, 10s, 20s
            print(f"Retrying after {wait_time}s...")
            time.sleep(wait_time)
        except Exception as e:
            # Don't retry on client errors (400, 401, 402, etc.)
            raise

Monitoring & Alerts

Set up monitoring to catch errors early:

Need Help?