Skip to main content

​
Error Handling

When an API request fails, you’ll receive a structured error response with details about what went wrong.

​
Error Response Format

All errors follow this consistent format: 
{
  "success": false,
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE"
  }
}
FieldDescription
successAlways false for error responses
error.messageA human-readable description of the error
error.codeA machine-readable error code for programmatic handling

​
Error Codes

​
Authentication Errors

CodeHTTP StatusDescription
AUTH_REQUIRED401No authentication was provided in the request headers
INVALID_API_KEY401The API key is invalid, malformed, or has expired
INVALID_AUTH_FORMAT401Token format not recognized (must start with sigmic_ or eyJ)
INVALID_TOKEN401JWT is invalid or has expired
JWT_NOT_CONFIGURED501Server does not have JWT signing configured
ORIGIN_NOT_ALLOWED403Request origin not in widget app’s allowed origins list
Example (API key): 
{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "AUTH_REQUIRED"
  }
}

​
Widget Token Errors

CodeHTTP StatusDescription
MISSING_CREDENTIALS400appId or appSecret not provided in token request
MISSING_END_USER_ID400endUserId not provided or empty
INVALID_CREDENTIALS401Widget app credentials are invalid
INVALID_EXPIRES_IN400expiresIn format invalid (must be e.g. "1h", "30m")
INVALID_ENV400Invalid env var name or non-string value
Example (token exchange): 
{
  "success": false,
  "error": {
    "message": "Invalid app credentials",
    "code": "INVALID_CREDENTIALS"
  }
}

​
Authorization Errors

CodeHTTP StatusDescription
FORBIDDEN403You don’t have permission to perform this action
These errors occur when your authentication is valid but you lack the required role. Common scenarios:
  • A member tries to perform an admin-only action (inviting members, changing roles)
  • A user tries to access a project they haven’t been granted access to
  • A non-admin tries to manage project members
Example: 
{
  "success": false,
  "error": {
    "message": "Admin access required."
  }
}

​
Resource Errors

CodeHTTP StatusDescription
NOT_FOUND404The requested resource (task, tool call) does not exist
Example: 
{
  "success": false,
  "error": {
    "message": "Task not found",
    "code": "NOT_FOUND"
  }
}

​
Validation Errors

CodeHTTP StatusDescription
VALIDATION_ERROR400Request parameters are invalid or missing
Examples: 
{
  "success": false,
  "error": {
    "message": "Message is required",
    "code": "VALIDATION_ERROR"
  }
}

{
  "success": false,
  "error": {
    "message": "Invalid env var name: 123BAD",
    "code": "VALIDATION_ERROR"
  }
}

​
Task Execution Errors

CodeHTTP StatusDescription
EXECUTION_ERROR500Task execution failed due to an internal error
ALREADY_RUNNING400Cannot perform action because task is already running
Example: 
{
  "success": false,
  "error": {
    "message": "Task is already running",
    "code": "ALREADY_RUNNING"
  }
}

​
Handling Errors in Code

​
JavaScript

async function makeRequest(url, options) {
  const response = await fetch(url, options);
  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'AUTH_REQUIRED':
      case 'INVALID_API_KEY':
        throw new Error('Authentication failed: ' + data.error.message);

      case 'NOT_FOUND':
        throw new Error('Resource not found: ' + data.error.message);

      case 'VALIDATION_ERROR':
        throw new Error('Invalid request: ' + data.error.message);

      default:
        throw new Error('API error: ' + data.error.message);
    }
  }

  return data;
}

​
Python

import requests

def make_request(url, **kwargs):
    response = requests.request(**kwargs, url=url)
    data = response.json()

    if not data.get('success'):
        error = data.get('error', {})
        code = error.get('code', 'UNKNOWN')
        message = error.get('message', 'Unknown error')

        if code in ['AUTH_REQUIRED', 'INVALID_API_KEY']:
            raise AuthenticationError(message)
        elif code == 'NOT_FOUND':
            raise NotFoundError(message)
        elif code == 'VALIDATION_ERROR':
            raise ValidationError(message)
        else:
            raise APIError(message)

    return data

​
SSE Stream Errors

Errors during streaming are delivered as error events: 
event: error
data: {"type":"error","data":{"message":"Task execution failed","code":"EXECUTION_ERROR"}}
Handle these within your SSE parsing logic: 
if (eventType === 'error') {
  console.error(`Error: ${data.data.message} (${data.data.code})`);
  // Clean up and handle the error
}

​
Best Practices

Always check success field

Even on 200 responses, verify success: true before processing data

Log error codes

Log the code field for debugging and monitoring

Implement retries

For transient errors (5xx), implement exponential backoff retries

Validate inputs

Validate inputs client-side to avoid unnecessary API calls