Error Codes

Complete reference of all error codes returned by the FrontDeskOS MCP server, with descriptions and resolution steps.

Error Response Format

All errors follow a consistent JSON format with a machine-readable code, human-readable message, and optional details about the specific failure.

Error response structurejson

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more input parameters failed validation.",
    "details": [
      {
        "field": "phone",
        "message": "Invalid phone number format. Expected E.164 format."
      }
    ],
    "request_id": "req_abc123"
  }
}

Request IDs

Every response includes a request_id. Include this ID when contacting support for faster issue resolution.

Error Reference

AUTH_INVALID_KEYHTTP 401

The API key provided is invalid or expired.

Resolution: Check your FRONTDESK_API_KEY environment variable. Generate a new key from the dashboard if expired.

AUTH_INSUFFICIENT_SCOPEHTTP 403

The API key does not have the required scope for this operation.

Resolution: Use a key with the required scope, or create a new key with broader permissions.

AUTH_WORKSPACE_MISMATCHHTTP 403

The API key does not belong to the specified workspace.

Resolution: Ensure FRONTDESK_WORKSPACE_ID matches the workspace the API key was created for.

RESOURCE_NOT_FOUNDHTTP 404

The requested resource (call, appointment, lead, etc.) was not found.

Resolution: Verify the ID is correct. The resource may have been deleted.

VALIDATION_ERRORHTTP 400

One or more input parameters failed validation.

Resolution: Check the error details for specific field validation failures.

CONFLICT_BOOKINGHTTP 409

The requested appointment slot is no longer available.

Resolution: Use frontdesk_check_availability to find available slots, then retry.

CONFLICT_DUPLICATEHTTP 409

A duplicate resource already exists (e.g., lead with same phone).

Resolution: Use the existing resource instead, or update it with new information.

RATE_LIMITEDHTTP 429

Too many requests. You have exceeded the rate limit.

Resolution: Wait and retry with exponential backoff. See Rate Limits page for details.

WORKSPACE_SUSPENDEDHTTP 403

The workspace has been suspended due to billing or policy issues.

Resolution: Contact support or resolve the billing issue in the dashboard.

TOOL_EXECUTION_ERRORHTTP 500

An internal error occurred while executing the tool.

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

INTEGRATION_ERRORHTTP 502

An error occurred communicating with a third-party integration.

Resolution: The external service may be temporarily unavailable. Retry after a short delay.

TIMEOUTHTTP 504

The operation timed out.

Resolution: The request took too long. Try with smaller result sets or simpler queries.

Error Handling Best Practices

Always check the code field for programmatic error handling, not the message.
Implement exponential backoff for RATE_LIMITED and TIMEOUT errors.
For CONFLICT_BOOKING, automatically fetch alternative slots.
Log the request_id for all errors to aid in debugging.
Never expose raw error details to end users -- map them to user-friendly messages.

Error Codes

Error Response Format

Error Reference

Error Handling Best Practices

Search Documentation