Error Codes

StyleGrab API returns structured error responses with machine-readable codes.

Error Response Format

{
  "error": {
    "code": "not_found",
    "message": "Extraction not found",
    "details": {}
  }
}

Authentication Errors

Code	HTTP Status	Description
`unauthorized`	401	Missing or invalid authentication
`token_expired`	401	JWT token has expired
`invalid_api_key`	401	API key is invalid or revoked
`forbidden`	403	Valid auth but insufficient permissions

Validation Errors

Code	HTTP Status	Description
`validation_error`	422	Request body failed validation
`invalid_url`	400	URL is malformed or unreachable
`invalid_webhook_url`	400	Webhook URL must be HTTPS
`missing_field`	400	Required field not provided

Example:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "fields": {
        "url": "must be a valid URL",
        "events": "must include at least one event"
      }
    }
  }
}

Resource Errors

Code	HTTP Status	Description
`not_found`	404	Resource does not exist
`already_exists`	409	Resource already exists
`conflict`	409	Operation conflicts with current state

Extraction Errors

Code	HTTP Status	Description
`extraction_failed`	422	Browser failed to load the page
`extraction_timeout`	422	Page load timed out
`page_blocked`	422	Page blocked the extraction
`invalid_content`	422	Page returned non-HTML content

Example:

{
  "error": {
    "code": "extraction_failed",
    "message": "Failed to load page",
    "details": {
      "reason": "SSL certificate error",
      "url": "https://example.com"
    }
  }
}

Rate Limiting

Code	HTTP Status	Description
`rate_limited`	429	Too many requests
`usage_limit_exceeded`	429	Monthly quota exceeded

Headers included:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800
Retry-After: 60

Billing Errors

Code	HTTP Status	Description
`subscription_required`	402	Feature requires paid plan
`subscription_expired`	402	Subscription has ended
`payment_failed`	402	Payment processing failed

Webhook Errors

Code	HTTP Status	Description
`webhook_delivery_failed`	—	Webhook endpoint returned non-2xx
`webhook_timeout`	—	Endpoint didn’t respond in time
`webhook_disabled`	—	Webhook was disabled after failures

Internal Errors

Code	HTTP Status	Description
`internal_error`	500	Unexpected server error
`service_unavailable`	503	Service temporarily unavailable

For 5xx errors, retry with exponential backoff. If the error persists, contact support.

Handling Errors

JavaScript

async function extractTokens(url) {
  const response = await fetch('https://api.stylegrab.dev/api/extractions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url })
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.error.code) {
      case 'rate_limited':
        const retryAfter = response.headers.get('Retry-After');
        await sleep(retryAfter * 1000);
        return extractTokens(url); // Retry
        
      case 'unauthorized':
        throw new Error('Invalid API key');
        
      case 'extraction_failed':
        console.error('Page could not be loaded:', error.error.details);
        return null;
        
      default:
        throw new Error(error.error.message);
    }
  }
  
  return response.json();
}

Python

import requests
import time

def extract_tokens(url):
    response = requests.post(
        'https://api.stylegrab.dev/api/extractions',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={'url': url}
    )
    
    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        return extract_tokens(url)
    
    if not response.ok:
        error = response.json()['error']
        raise Exception(f"{error['code']}: {error['message']}")
    
    return response.json()

Keyboard shortcuts

StyleGrab Documentation