Error Handling

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    },
    "request_id": "req_abc123",
    "documentation_url": "https://docs.run-agent.ai/errors/ERROR_CODE"
  }
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid",
    "status": 401
  }
}

{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "The API key has expired",
    "status": 401
  }
}

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field 'query' is missing",
    "details": {
      "field": "query",
      "requirement": "string, min length 1"
    },
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_FIELD_TYPE",
    "message": "Field 'temperature' must be a number",
    "details": {
      "field": "temperature",
      "provided": "string",
      "expected": "number"
    },
    "status": 400
  }
}

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 'agent-123' not found",
    "details": {
      "agent_id": "agent-123"
    },
    "status": 404
  }
}

{
  "error": {
    "code": "DEPLOYMENT_FAILED",
    "message": "Failed to deploy agent",
    "details": {
      "reason": "Invalid configuration",
      "validation_errors": ["Missing entrypoint"]
    },
    "status": 422
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2024-01-01T00:00:00Z"
    },
    "status": 429
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred",
    "request_id": "req_xyz789",
    "status": 500
  }
}

import requests
from time import sleep

def call_api_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=data)
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                # Rate limited - wait and retry
                retry_after = int(e.response.headers.get('Retry-After', 60))
                sleep(retry_after)
                continue
                
            elif e.response.status_code >= 500:
                # Server error - retry with backoff
                if attempt < max_retries - 1:
                    sleep(2 ** attempt)
                    continue
                    
            # Don't retry client errors (4xx)
            error_data = e.response.json()
            raise Exception(f"API Error: {error_data['error']['message']}")
            
        except requests.exceptions.RequestException as e:
            # Network error - retry
            if attempt < max_retries - 1:
                sleep(2 ** attempt)
                continue
            raise
    
    raise Exception("Max retries exceeded")

async function callAPIWithRetry(url, data, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${API_KEY}`
        },
        body: JSON.stringify(data)
      });

      if (!response.ok) {
        const error = await response.json();
        
        if (response.status === 429) {
          // Rate limited
          const retryAfter = response.headers.get('Retry-After') || 60;
          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
          continue;
        }
        
        if (response.status >= 500 && attempt < maxRetries - 1) {
          // Server error - retry with exponential backoff
          await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
          continue;
        }
        
        throw new Error(error.error.message);
      }

      return await response.json();
      
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      // Network error - retry
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

# Contact support with request ID
"request_id": "req_abc123xyz"

import logging

logging.basicConfig(level=logging.DEBUG)

# Now SDK will log all requests/responses
client = RunAgentClient(agent_id="...", debug=True)

@app.post("/webhook")
async def handle_webhook(request):
    try:
        # Process webhook
        data = await request.json()
        process_webhook(data)
        return {"status": "success"}
        
    except ValidationError:
        # Return 400 for validation errors
        return JSONResponse(
            status_code=400,
            content={"error": "Invalid webhook data"}
        )
        
    except Exception as e:
        # Return 500 for server errors
        # RunAgent will retry 500 errors
        return JSONResponse(
            status_code=500,
            content={"error": "Internal error"}
        )