Error Handling

The SpecStory Cloud API uses conventional HTTP response codes to indicate the success or failure of an API request. Error responses include detailed information to help you understand and resolve issues.

HTTP Status Codes

Success Codes

Code	Status	Description
`200`	OK	Request succeeded
`304`	Not Modified	Resource hasn’t changed (ETag match)

Client Error Codes

Code	Status	Description
`400`	Bad Request	Invalid request format or parameters
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource doesn’t exist
`429`	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Status	Description
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Temporary server issue
`503`	Service Unavailable	Server temporarily unavailable

Error Response Format

All error responses follow a consistent JSON structure:

{
  "success": false,
  "error": "Descriptive error message"
}

Example Error Responses

{
  "success": false,
  "error": "Invalid session token"
}

Authentication Errors

401 Unauthorized

Causes:

Missing Authorization header
Invalid or expired API key
Malformed Bearer token

Solutions:

Verify your API key is correct
Check the Authorization header format: Bearer YOUR_API_KEY
Generate a new API key if the current one is expired

curl -H "Authorization: Bearer sk_live_abc123..." \
  https://cloud.specstory.com/api/v1/projects

403 Forbidden

Causes:

Attempting to access another user’s resources
API key lacks required permissions
Resource access restrictions

Solutions:

Verify you’re accessing your own projects/sessions
Check API key permissions in the dashboard
Ensure the resource ID is correct

Resource Errors

404 Not Found

Common scenarios:

Project Not Found

{
  "success": false,
  "error": "Project not found"
}

Causes:

Invalid project ID
Project was deleted
No access to the project

Solutions:

Verify the project ID exists
Check if you have access to the project
Use GET /api/v1/projects to list available projects

Session Not Found

{
  "success": false,
  "error": "Session not found"
}

Causes:

Invalid session ID
Session was deleted
Session belongs to a different project

Solutions:

Verify the session ID and project ID combination
Use GET /api/v1/projects/{projectId}/sessions to list sessions
Check if the session was recently deleted

Rate Limiting

429 Too Many Requests

The API implements rate limiting to ensure service quality:

REST API: 1000 requests per hour
GraphQL API: 500 queries per hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Handling rate limits:

async function makeRequest(url, options) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitTime = (resetTime * 1000) - Date.now();
    
    console.log(`Rate limited. Waiting ${waitTime}ms`);
    await new Promise(resolve => setTimeout(resolve, waitTime));
    
    // Retry the request
    return makeRequest(url, options);
  }
  
  return response;
}

GraphQL Errors

GraphQL errors are returned in the errors array alongside any partial data:

{
  "data": {
    "project": null
  },
  "errors": [
    {
      "message": "Project not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["project"],
      "extensions": {
        "code": "NOT_FOUND",
        "projectId": "invalid-id"
      }
    }
  ]
}

Common GraphQL Error Codes

Code	Description	Solution
`UNAUTHENTICATED`	Missing or invalid authentication	Check Authorization header
`FORBIDDEN`	Insufficient permissions	Verify resource access
`NOT_FOUND`	Resource doesn’t exist	Check resource ID
`VALIDATION_ERROR`	Invalid query or variables	Review query syntax
`RATE_LIMITED`	Too many requests	Implement backoff strategy

Validation Errors

400 Bad Request

Request validation failures:

Invalid JSON

{
  "success": false,
  "error": "Invalid JSON in request body"
}

Causes:

Malformed JSON syntax
Missing required Content-Type header

Solutions:

Validate JSON syntax
Include Content-Type: application/json header

Missing Required Fields

{
  "success": false,
  "error": "Missing required field: name"
}

Causes:

Required parameters not provided
Incorrect parameter names

Solutions:

Check API documentation for required fields
Verify parameter spelling and case

Invalid Parameter Values

{
  "success": false,
  "error": "Invalid value for color. Must be one of: rose, pink, orange, amber, emerald, cyan, blue, purple, slate, gray"
}

Causes:

Parameter values outside allowed range
Incorrect data types

Solutions:

Check allowed values in API documentation
Verify data types match expected format

Error Handling Best Practices

Implement Retry Logic

async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      // Success
      if (response.ok) {
        return await response.json();
      }
      
      // Client errors (4xx) - don't retry
      if (response.status >= 400 && response.status < 500) {
        const error = await response.json();
        throw new Error(error.error);
      }
      
      // Server errors (5xx) - retry with backoff
      if (attempt === maxRetries) {
        throw new Error(`Request failed after ${maxRetries} attempts`);
      }
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

Log Errors for Debugging

function handleApiError(error, context) {
  console.error('API Error:', {
    message: error.message,
    context: context,
    timestamp: new Date().toISOString(),
    stack: error.stack
  });
  
  // Report to error tracking service
  // errorTracker.captureException(error, { context });
}

Graceful Degradation

async function getProjectSessions(projectId) {
  try {
    const response = await fetch(`/api/v1/projects/${projectId}/sessions`);
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    return await response.json();
    
  } catch (error) {
    console.warn('Failed to load sessions:', error.message);
    
    // Return empty state instead of crashing
    return {
      success: true,
      data: {
        sessions: [],
        total: 0,
        projectId: projectId
      }
    };
  }
}

Troubleshooting Checklist

When encountering API errors:

Check Authentication
- Verify API key is valid and not expired
- Ensure proper Authorization header format
- Test with a simple request like GET /api/v1/projects
Validate Request Format
- Check JSON syntax and structure
- Verify required fields are included
- Ensure parameter values are within allowed ranges
Review Resource Access
- Confirm resource IDs exist and are accessible
- Check if you have permissions for the operation
- Verify project/session relationships
Monitor Rate Limits
- Check rate limit headers in responses
- Implement appropriate backoff strategies
- Consider caching frequently accessed data
Test with GraphQL Playground
- Use the interactive playground to test queries
- Validate GraphQL syntax and variables
- Explore schema documentation for available fields

Getting Help

If you’re still experiencing issues:

Check our status page for service incidents
Search existing issues on GitHub
Contact support at support@specstory.com
Join our community on Slack

Include the following information when reporting issues:

Request URL and method
Request headers and body
Response status code and body
Timestamp of the request
Your API key ID (not the full key)

API Reference

Projects

Sessions

GraphQL

Error Handling

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Response Format

Example Error Responses

Authentication Errors

401 Unauthorized

403 Forbidden

Resource Errors

404 Not Found

Rate Limiting

429 Too Many Requests

GraphQL Errors

Common GraphQL Error Codes

Validation Errors

400 Bad Request

Error Handling Best Practices

Implement Retry Logic

Log Errors for Debugging

Graceful Degradation

Troubleshooting Checklist

Getting Help

API Reference

Projects

Sessions

GraphQL

Error Handling

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Error Response Format

​Example Error Responses

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Resource Errors

​404 Not Found

​Rate Limiting

​429 Too Many Requests

​GraphQL Errors

​Common GraphQL Error Codes

​Validation Errors

​400 Bad Request

​Error Handling Best Practices

​Implement Retry Logic

​Log Errors for Debugging

​Graceful Degradation

​Troubleshooting Checklist

​Getting Help

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Response Format

Example Error Responses

Authentication Errors

401 Unauthorized

403 Forbidden

Resource Errors

404 Not Found

Rate Limiting

429 Too Many Requests

GraphQL Errors

Common GraphQL Error Codes

Validation Errors

400 Bad Request

Error Handling Best Practices

Implement Retry Logic

Log Errors for Debugging

Graceful Degradation

Troubleshooting Checklist

Getting Help