Error Handling

The Tokencraft API uses conventional HTTP status codes to indicate success or failure of requests. All error responses include a JSON body with an error field describing the problem.

Error Response Format

{
  "error": "Error message describing what went wrong"
}

Status Codes

2xx Success

Code	Description
`200`	OK - Request succeeded
`201`	Created - Resource created successfully

4xx Client Errors

Code	Description
`400`	Bad Request - Invalid input or parameters
`401`	Unauthorized - Missing or invalid authentication
`403`	Forbidden - Valid auth but insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded

5xx Server Errors

Code	Description
`500`	Internal Server Error - Something went wrong on our end
`503`	Service Unavailable - Temporary outage

Common Errors

401 Unauthorized

Cause: Missing or invalid API token

{
  "error": "Invalid API token"
}

Solutions:

Verify your token is correct
Check the Authorization header format: Bearer tkc_xxx
Ensure the token hasn’t been revoked
Generate a new token if necessary

Example:

# ❌ Wrong
curl https://app.tokencraft.dev/api/v1/workspaces

# ✅ Correct
curl -H "Authorization: Bearer tkc_your_token" \
  https://app.tokencraft.dev/api/v1/workspaces

404 Not Found

Cause: Resource doesn’t exist or you don’t have access

{
  "error": "Workspace not found"
}

{
  "error": "Tokenset not found"
}

Solutions:

Verify the resource ID is correct
Ensure you have access to the resource
Check for typos in the endpoint URL

403 Forbidden

Cause: Scope missing or workspace role/plan does not allow the operation

{
  "error": "This operation requires the 'write:tokens' scope"
}

{
  "error": "Your workspace role does not allow API write operations on this TEAM workspace."
}

{
  "error": "API write access is not available for this workspace owner's current plan."
}

Solutions:

Ensure your token includes the required scope (write:tokens or export:tokens)
Verify your workspace role (TEAM viewers cannot write)
Verify the workspace owner plan allows API write access

410 Gone (Deprecated Session Endpoint)

Cause: Legacy workspace invitation link endpoints are deprecated

{
  "error": "Workspace invitation links are deprecated. Members are now added instantly from workspace settings."
}

Affected endpoints:

POST /api/workspaces/invitations/accept
GET /api/workspaces/invitations/verify
DELETE /api/workspaces/invitations/{id}

400 Bad Request

Cause: Invalid input data

{
  "error": "Name is required"
}

{
  "error": "Invalid token type"
}

Solutions:

Check required fields are provided
Validate input format matches API expectations
Review the endpoint documentation

Example:

# ❌ Wrong - missing required field
curl -X POST https://app.tokencraft.dev/api/v1/workspaces \
  -H "Authorization: Bearer tkc_token" \
  -H "Content-Type: application/json" \
  -d '{}'

# ✅ Correct
curl -X POST https://app.tokencraft.dev/api/v1/workspaces \
  -H "Authorization: Bearer tkc_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Workspace"}'

429 Rate Limit Exceeded

Cause: Too many requests in a short time

{
  "error": "Rate limit exceeded. Please try again later."
}

Solutions:

Wait 60 seconds before retrying
Implement exponential backoff
Reduce request frequency
Cache API responses

See Rate Limits for details.

500 Internal Server Error

Cause: Server-side error

{
  "error": "Internal server error"
}

Solutions:

Retry the request after a short delay
Check status page for outages
Contact support if the issue persists

Error Handling Examples

JavaScript/TypeScript

async function fetchWorkspaces(token) {
  try {
    const response = await fetch('https://app.tokencraft.dev/api/v1/workspaces', {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          throw new Error('Authentication failed. Check your API token.');
        case 404:
          throw new Error('Resource not found.');
        case 429:
          throw new Error('Rate limit exceeded. Please wait and try again.');
        case 500:
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(error.error || 'An error occurred');
      }
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error.message);
    throw error;
  }
}

Python

import requests
from time import sleep

def fetch_workspaces(token):
    headers = {'Authorization': f'Bearer {token}'}
    
    try:
        response = requests.get(
            'https://app.tokencraft.dev/api/v1/workspaces',
            headers=headers
        )
        
        response.raise_for_status()
        return response.json()
        
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            raise Exception('Authentication failed. Check your API token.')
        elif e.response.status_code == 404:
            raise Exception('Resource not found.')
        elif e.response.status_code == 429:
            raise Exception('Rate limit exceeded. Please wait and try again.')
        elif e.response.status_code == 500:
            raise Exception('Server error. Please try again later.')
        else:
            error_data = e.response.json()
            raise Exception(error_data.get('error', 'An error occurred'))
    
    except requests.exceptions.RequestException as e:
        raise Exception(f'Network error: {str(e)}')

With Retry Logic

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      // Don't retry client errors (except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        const error = await response.json();
        throw new Error(error.error || 'Client error');
      }

      // Retry on rate limit or server error
      if (response.status === 429 || response.status >= 500) {
        const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.log(`Attempt ${attempt + 1} failed. Retrying in ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error || 'Request failed');
      }

      return await response.json();

    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
    }
  }

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

// Usage
try {
  const data = await fetchWithRetry(
    'https://app.tokencraft.dev/api/v1/workspaces',
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  console.log(data);
} catch (error) {
  console.error('Failed to fetch workspaces:', error.message);
}

Validation Errors

When creating or updating resources, validation errors provide specific field information:

{
  "error": "Name is required"
}

{
  "error": "Invalid token type. Supported types: color, dimension, fontFamily, fontWeight, fontSize, lineHeight, letterSpacing, duration, cubicBezier, number, strokeStyle, border, transition, shadow, gradient, typography"
}

Best Practices

1. Always Check Response Status

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error);
}

2. Implement Retry Logic

For rate limits and server errors:

const maxRetries = 3;
const backoff = [1000, 2000, 4000]; // ms

for (let i = 0; i < maxRetries; i++) {
  try {
    return await makeRequest();
  } catch (error) {
    if (i === maxRetries - 1) throw error;
    await sleep(backoff[i]);
  }
}

3. Log Errors Appropriately

console.error('API Error:', {
  status: response.status,
  error: errorData.error,
  endpoint: url,
  timestamp: new Date().toISOString()
});

4. Provide User-Friendly Messages

function getUserMessage(statusCode, error) {
  const messages = {
    401: 'Please check your API credentials and try again.',
    404: 'The requested resource was not found.',
    429: 'Too many requests. Please wait a moment and try again.',
    500: 'Something went wrong. Please try again later.'
  };
  
  return messages[statusCode] || error || 'An unexpected error occurred.';
}

Debugging Tips

1. Use Verbose Logging

curl -v -H "Authorization: Bearer tkc_token" \
  https://app.tokencraft.dev/api/v1/workspaces

2. Check Request Format

Ensure:

Authorization header is present and correct
Content-Type header is set for POST/PATCH
Request body is valid JSON
URL is properly formatted

3. Validate Token

Test your token with a simple request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/workspaces

4. Check Rate Limit Headers

Response headers include rate limit info:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1633024800

Getting Help

If you encounter persistent errors:

Check the documentation
Review your request format and authentication
Check for service status updates
Contact support with:
- Request details (endpoint, method, headers)
- Response status and error message
- Timestamp of the request
- Your API token ID (not the full token)

​Error Handling

​Error Response Format

​Status Codes

​2xx Success

​4xx Client Errors

​5xx Server Errors

​Common Errors

​401 Unauthorized

​404 Not Found

​403 Forbidden

​410 Gone (Deprecated Session Endpoint)

​400 Bad Request

​429 Rate Limit Exceeded

​500 Internal Server Error

​Error Handling Examples

​JavaScript/TypeScript

​Python

​With Retry Logic

​Validation Errors

​Best Practices

​1. Always Check Response Status

​2. Implement Retry Logic

​3. Log Errors Appropriately

​4. Provide User-Friendly Messages

​Debugging Tips

​1. Use Verbose Logging

​2. Check Request Format

​3. Validate Token

​4. Check Rate Limit Headers

​Getting Help

​Next Steps

Rate Limits

Authentication

Error Handling

Error Response Format

Status Codes

2xx Success

4xx Client Errors

5xx Server Errors

Common Errors

401 Unauthorized

404 Not Found

403 Forbidden

410 Gone (Deprecated Session Endpoint)

400 Bad Request

429 Rate Limit Exceeded

500 Internal Server Error

Error Handling Examples

JavaScript/TypeScript

Python

With Retry Logic

Validation Errors

Best Practices

1. Always Check Response Status

2. Implement Retry Logic

3. Log Errors Appropriately

4. Provide User-Friendly Messages

Debugging Tips

1. Use Verbose Logging

2. Check Request Format

3. Validate Token

4. Check Rate Limit Headers

Getting Help

Next Steps