Error Handling

Learn how to handle errors gracefully and build robust applications with Sematryx.

Error Response Format

All errors are returned as JSON objects with a consistent structure:

Error response format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'bounds' parameter is required",
    "field": "bounds",
    "request_id": "req_1234567890"
  }
}

Error Fields

code: Machine-readable error code
message: Human-readable error message
field: (Optional) Field name if validation error
request_id: Unique request ID for support inquiries

Error Codes

Code	HTTP Status	Description
`invalid_request`	400	Request parameters are invalid or missing
`authentication_error`	401	Invalid or missing API key
`forbidden`	403	API key does not have permission for this operation
`not_found`	404	Requested resource not found
`rate_limit_error`	429	Rate limit exceeded
`server_error`	500	Internal server error
`service_unavailable`	503	Service temporarily unavailable

Handling Errors in Python

The Python SDK provides specific exception types for different error scenarios:

Python error handling

from aeao.exceptions import (
    SematryxError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    NotFoundError,
    ServerError
)

try:
    result = client.optimize(
        objective_function=objective,
        bounds=bounds
    )
except AuthenticationError:
    print("Invalid API key. Please check your credentials.")
except RateLimitError as e:
    print(f"Rate limit exceeded. Reset at: {e.reset_time}")
except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Field: {e.field}")
except NotFoundError:
    print("Resource not found.")
except ServerError:
    print("Server error. Please try again later.")
except SematryxError as e:
    print(f"Error: {e.message}")

Handling Errors in JavaScript

The JavaScript SDK throws errors with consistent structure:

JavaScript error handling

try {
  const result = await aeao.optimize({
    objective_function: objective,
    bounds: bounds
  })
} catch (error) {
  switch (error.code) {
    case 'authentication_error':
      console.error('Invalid API key')
      break
    case 'rate_limit_error':
      console.error('Rate limit exceeded. Reset at: ' + error.resetTime)
      break
    case 'validation_error':
      console.error('Validation error: ' + error.message)
      console.error('Field: ' + error.field)
      break
    case 'not_found':
      console.error('Resource not found')
      break
    case 'server_error':
      console.error('Server error. Please try again later.')
      break
    default:
      console.error('Error: ' + error.message)
  }
}

Retry Logic

Implement retry logic for transient errors (rate limits, server errors):

Retry logic with exponential backoff

import time
from aeao.exceptions import RateLimitError, ServerError

def make_request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt < max_retries - 1:
                wait_time = e.reset_time - time.time()
                time.sleep(max(wait_time, 1))
                continue
            raise
        except ServerError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
    raise Exception("Max retries exceeded")

When to Retry

Rate Limit Errors (429): Always retry after waiting for reset time
Server Errors (500, 503): Retry with exponential backoff
Network Errors: Retry for transient network issues
Don't Retry: Authentication errors (401), validation errors (400), not found (404)

Best Practices

✅ Do

Always handle errors explicitly
Log errors with request IDs for debugging
Implement retry logic for transient errors
Provide user-friendly error messages
Validate input before making API calls
Monitor error rates and patterns

❌ Don't

Ignore errors silently
Retry non-retryable errors (401, 400, 404)
Expose internal error details to end users
Retry indefinitely without limits
Make assumptions about error causes

Debugging Errors

When debugging errors, use the request ID to get help from support:

Request ID

Every error response includes a request_id field. This unique identifier helps our support team quickly locate and diagnose issues.

Include the request ID when contacting support or reporting bugs.