Reference

Error Handling

Learn how to handle errors from BotEsq API calls. All errors follow a consistent format and include actionable information for resolution.

Error Response Format

All errors return a consistent JSON structure:

json

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account does not have enough credits for this operation",
    "details": {
      "required_credits": 10000,
      "available_credits": 5000,
      "operation": "create_matter"
    },
    "request_id": "req_abc123..."
  }
}

Field	Type	Description
code	string	Machine-readable error code
message	string	Human-readable error message
details	object	Additional context (varies by error)
request_id	string	Unique ID for support inquiries

Handling Errors

Here is a recommended pattern for handling BotEsq errors:

typescript

async function callBotEsq(tool: string, params: object) {
  try {
    const result = await mcp.callTool(tool, params);
    return result;
  } catch (error) {
    if (error.code === 'SESSION_EXPIRED') {
      // Refresh session and retry
      await refreshSession();
      return mcp.callTool(tool, params);
    }
 
    if (error.code === 'INSUFFICIENT_CREDITS') {
      // Notify user or auto-purchase credits
      console.log(`Need ${error.details.required_credits} credits`);
      throw new Error('Insufficient credits for this operation');
    }
 
    if (error.code === 'RATE_LIMITED') {
      // Implement exponential backoff
      const retryAfter = error.details.retry_after || 60;
      await sleep(retryAfter * 1000);
      return mcp.callTool(tool, params);
    }
 
    // Log unexpected errors for debugging
    console.error(`BotEsq error: ${error.code}`, {
      message: error.message,
      request_id: error.request_id
    });
 
    throw error;
  }
}

Authentication Errors

INVALID_API_KEY

401

The provided API key is invalid, malformed, or has been revoked.

Resolution: Check your API key in the operator dashboard. Ensure you are using the correct environment (live vs test).

SESSION_EXPIRED

401

The session token has expired due to inactivity (24 hours) or explicit logout.

Resolution: Call start_session again to create a new session.

INVALID_SESSION

401

The session token is invalid or does not exist.

Resolution: Call start_session to create a valid session.

UNAUTHORIZED_SERVICE

403

Your operator account is not authorized for this service.

Resolution: Contact support to enable the required service for your account.

Validation Errors

VALIDATION_ERROR

400

One or more parameters failed validation.

Resolution: Check the error details for specific field errors and correct your input.

MISSING_PARAMETER

400

A required parameter was not provided.

Resolution: Include all required parameters in your request.

INVALID_PARAMETER

400

A parameter value is invalid or out of range.

Resolution: Check parameter constraints in the documentation.

Credit Errors

INSUFFICIENT_CREDITS

402

Your account does not have enough credits for this operation.

Resolution: Add credits using the add_credits tool or through the operator dashboard.

CREDIT_LIMIT_EXCEEDED

402

This operation would exceed your account credit limit.

Resolution: Contact support to increase your credit limit.

PAYMENT_FAILED

402

The payment for credit purchase failed.

Resolution: Check your payment method in the operator dashboard.

Resource Errors

MATTER_NOT_FOUND

404

The specified matter does not exist or is not accessible.

Resolution: Verify the matter_id and ensure it belongs to your account.

DOCUMENT_NOT_FOUND

404

The specified document does not exist or is not accessible.

Resolution: Verify the document_id and ensure it belongs to your account.

CONSULTATION_NOT_FOUND

404

The specified consultation does not exist or is not accessible.

Resolution: Verify the consultation_id and ensure it belongs to your account.

RETAINER_NOT_FOUND

404

The specified retainer does not exist or has expired.

Resolution: Call get_retainer_terms to get a fresh retainer offer.

State Errors

RETAINER_REQUIRED

409

This operation requires an accepted retainer agreement.

Resolution: Call get_retainer_terms and accept_retainer before proceeding.

MATTER_NOT_ACTIVE

409

The matter is not in an active state.

Resolution: Check matter status. May need to accept retainer or reopen the matter.

DOCUMENT_PROCESSING

409

The document is still being processed.

Resolution: Wait and retry. Check status with get_document_analysis.

CONSULTATION_PENDING

409

The consultation is still pending attorney review.

Resolution: Wait and retry. Check status with get_consultation_result.

Rate Limiting

RATE_LIMITED

429

Too many requests. You have exceeded the rate limit.

Resolution: Implement exponential backoff. Check Retry-After header.

CONCURRENT_LIMIT

429

Too many concurrent requests from this session.

Resolution: Reduce parallel requests. Wait for pending requests to complete.

Server Errors

INTERNAL_ERROR

500

An unexpected internal error occurred.

Resolution: Retry the request. If persistent, contact support with the request ID.

SERVICE_UNAVAILABLE

503

The service is temporarily unavailable.

Resolution: Retry with exponential backoff. Check status page for outages.

Retry Strategy

For transient errors (5xx, rate limits), use exponential backoff:

typescript

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  let lastError: Error;
 
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
 
      // Don't retry client errors (except rate limits)
      if (error.status >= 400 && error.status < 500 && error.code !== 'RATE_LIMITED') {
        throw error;
      }
 
      // Calculate delay with jitter
      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
 
  throw lastError;
}