Error Handling Guide

This guide explains how errors are structured in the Facilitron Public API and best practices for handling them in your integration.

Error Response Format

All API error responses follow a consistent structure:

Code
 
{
  "message": "Human-readable error description",
  "message_code": "Specific error code (e.g., PR001, SY003)",
  "invocation_id": "a2727bfe-d9aa-4155-ae86-06871a90238a"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the general category of response:

Status Code	Description
200	OK – The request was successful
400	Bad Request – The request contains invalid parameters or is malformed
401	Unauthorized – Authentication credentials are missing or invalid
403	Forbidden – Authentication succeeded, but you don't have permission
404	Not Found – The requested resource could not be found
409	Conflict – The request could not be completed due to a conflict
429	Too Many Requests – You’ve exceeded your rate limit quota
500	Internal Server Error – Something went wrong on our end
502	Bad Gateway – Received an invalid response from the upstream server
503	Service Unavailable – Server timeout or service is temporarily unavailable
504	Gateway Timeout – The server didn't respond in time

• ** not all endpoints support all error status codes. See API Overview for details

Error Code Categories

Error codes are categorized by domain to simplify troubleshooting:

Prefix	Category	Description
PR###	Property	Property-related errors (e.g., not found, access denied)
FC###	Facility	Facility-related errors (e.g., not found, access denied)
EV###	Event	Event-related errors (e.g., not found, invalid state, conflict, duplicate)
SY###	System	System-level errors (e.g., validation, upstream service, timeout)
US###	User	User-related errors (e.g., user not found, invalid renter)
AU###	Authentication	Authentication and authorization errors (e.g., missing or invalid API key)
AC###	Account Config	API key and user-role related configuration errors
AT###	Activity Type	Activity-type-specific errors (e.g., not found)
RC###	Rate Category	Rate-category-specific errors (e.g., not found)
A###	Success	Success codes for confirming normal operations

Detailed Error Codes

Property Errors (PR###)

Code	Description	Resolution
PR001	Property not found – The property with the specified ID does not exist.	Check that the property ID is correct.
PR002	Property access denied – The API user does not have permission to access this property.	Verify your API user has been granted access to this property.
PR003	Property retrieval failed – An error occurred while fetching property details.	Try again later or contact support if the issue persists.

Facility Errors (FC###)

Code	Description	Resolution
FC001	Facility not found – The facility with the specified ID could not be located.	Verify the facility ID exists and is active.
FC002	Facility access denied – The facility belongs to a different property and cannot be queried.	Confirm that the facility belongs to a property your API user can access.
FC003	Facility retrieval failed – An error occurred while fetching facility details.	Try again or contact support if the issue persists.

Event Errors (EV###)

Code	Description	Resolution
EV001	Event not found – No event exists for the provided identifier.	Verify the event ID is correct.
EV002	Time slot not found – The requested time slot for the event does not exist.	Check the time slot ID.
EV004	Event is already declined – The event has been declined and cannot be cancelled or modified.	No action needed - event is already in declined state.
EV005	Event is already cancelled – The event has been cancelled.	No action needed - event is already cancelled.
EV006	Event cannot be modified – The event was not created via the API.	Only events created through the API can be modified through the API.
EV007	Event update failed – An error occurred while updating the event.	Check your inputs and try again.
EV008	Duplicate event creation – The event was already created; duplicate creations are not allowed.	Verify the event doesn't already exist by checking the external_system_event_id.
EV009	Conflicting event schedule – The event conflicts with another scheduled event.	Choose a different time slot that doesn't conflict with existing events.
EV010	Event cancellation failed – An error occurred while cancelling the event.	Try again or contact support.

System Errors (SY###)

Code	Description	Resolution
SY001	Validation failed – One or more input parameters are invalid or missing. This includes invalid date ranges where the provided date range exceeds the maximum allowed period (31 days) or includes past dates.	Check the request parameters for correct format and required fields. For date ranges, ensure they don't exceed 31 days and don't include past dates.
SY002	Configuration error – Account misconfiguration; please contact support.	Contact Facilitron support for assistance.
SY003	Timeout error – The operation timed out before completion.	Try breaking down your request into smaller chunks or try at a less busy time.
SY004	Internal server error – An unexpected error occurred.	Contact Facilitron support with the invocation_id for assistance.
SY005	Data processing error – There was an error processing the request data.	Check your request data format.
SY006	Too Many Requests – Your account has exceeded the allowed number of requests.	Reduce the request frequency.

Authentication Errors (AU###)

Code	Description	Resolution
AU001	Missing API key – The request is missing a required API key in the headers.	Include both the API key and API User ID in your request headers.
AU002	Unable to authenticate – The provided API credentials are invalid or missing.	Verify your API credentials are correct.
AU003	Insufficient permissions – The API user does not have sufficient permissions to perform this operation.	Your API user needs additional permissions for this operation.

AWS Lambda Specific Error Handling

Our API is implemented using AWS Lambda functions with specific timeout configurations:

• Read operations (GET): 30-second timeout
• Write operations (POST, PATCH): 30-second timeout

If you receive a SY003 Timeout error or a 503 Service Unavailable response, your request might be:

• Too large (trying to query too much data at once)
• Made during a period of high system load
• Getting delayed by a Lambda cold start (this will only account for a few seconds of the delay)

Best Practices for Error Handling

1. Always check the status code first to determine the category of error.
2. Parse the error response to extract the message_code and message.
3. Implement retry logic for 429 (rate limit) and 5xx (server) errors with exponential backoff.
4. Log the invocation_id for all errors to help with troubleshooting.
5. Respect rate limits to avoid being throttled.
6. For date range errors (SY001), ensure you're requesting 31 days or less and not including past dates.

Implementing a Robust Error Handler

Here's a pseudocode example of a robust error handling approach that accounts for different error formats:

Code
 
async function callFacilitronAPI(endpoint, options) {
  try {
    const response = await fetch(endpoint, options);

    // Handle 'Too many requests' and Authentication erros
    if (data.message_code === 'SY006' || data.message_code.startsWith('AU')) {
      const errorData = await response.json();

      if (data.message_code === 'SY006') {
        logError(`Rate Limit Error: ${errorData.message}`, errorData.invocation_id);
        return handleRateLimitError(errorData);
      } else {
        logError(`Authentication Error: ${errorData.message}`, errorData.invocation_id);
        return handleAuthError(errorData);
      }
    }

    // Successfully received a response from the server
    const data = await response.json();

    // Check if the response is an error despite a 200 status code
    if (data.message_code && !data.message_code.startsWith('A')) {
      // Handle API-level error
      logError(`API Error: ${data.message_code} - ${data.message}`, data.invocation_id);
      return handleAPIError(data);
    }

    // Success case
    return data;
  } catch (error) {
    // Network or parsing error
    logError(`Network Error: ${error.message}`);
    return handleNetworkError(error);
  }
}

function handleAuthError(errorData) {
  // Reference the invocation_id for support
  const requestId = errorData.invocation_id;

  if (errorData.message_code === "AU001") {
    // Missing authorization header
    return {
      success: false,
      error: "Missing API credentials. Please include Authorization header with a value of Bearer YOUR_KEY_HERE",
      requestId
    };
  } else {
    // Invalid API key
    return {
      success: false,
      error: "Invalid API credentials. Please check your Authorization header is set to Bearer YOUR_KEY_HERE and that your key is correct.",
      requestId
    };
  }
}

Response Examples By Status Code

This section provides concrete examples of responses for each status code you might encounter when using the API.

200 OK: Successful Response

Code
 
{
  "message": "Properties retrieved successfully – The property details have been successfully retrieved.",
  "message_code": "A007",
  "invocation_id": "a2727bfe-d9aa-4155-ae86-06871a90238a",
  "properties": [
    {
      "_id": "67d3d98234e4730d41310bd2",
      "u_id": "139d71e8662595e3ba37",
      "name": "Generic API - Organization (Not searchable)",
      "address": "Hilo",
      "city": "Hilo",
      "state": "HI",
      "zip": "96720",
      "timezone": "Pacific/Honolulu",
      "properties": [
        "567b230c8ff7f511007cb449"
      ]
    },
    {
      "_id": "567b230c8ff7f511007cb449",
      "u_id": "res2345",
      "name": "Child Organization",
      "address": "21370 Homestead Rd",
      "city": "Cupertino",
      "state": "CA",
      "zip": "95014",
      "timezone": "America/Los_Angeles",
      "properties": []
    }
  ]
}

Context: This indicates a successful API call. Note that success responses include a message_code that starts with "A".

Handling: Process the data as needed in your application.

400 Bad Request: Invalid Parameters

Code
 
{
  "message": "Validation failed – One or more input parameters are invalid or missing.",
  "message_code": "SY001",
  "invocation_id": "b8749cfe-d6bb-4266-9055-454ca2e51246"
}

Context: This error occurs when your request contains invalid parameters. In this example, the date range specified exceeds the 31-day maximum.

Handling: Validate input parameters before making API calls. For date ranges, ensure they don't exceed 31 days.

401 Unauthorized: Authentication Failure

Code
 
{
  "message": "Unable to authenticate – The provided API credentials are invalid or missing.",
  "message_code": "AU002",
  "invocation_id": "b8749cfe-d6bb-4266-9055-454ca2e51246"
}

Context: This error occurs when the API key is invalid, or expired.

Handling: Verify that your API credentials are correct.

Code
 
{
  "message": "Missing API key – The request is missing a required API key in the headers.",
  "message_code": "AU001",
  "invocation_id": "b8749cfe-d6bb-4266-9055-454ca2e51246"
}

Context: This error occurs when the API key is missing.

Handling: Verify that your API credentials are properly included in the request headers.

403 Forbidden: Access Denied

Code
 
{
  "message": "Property access denied – The API user does not have permission to access this property.",
  "message_code": "PR002",
  "invocation_id": "3861af64-91aa-4d0a-8944-343ba1e40145"
}

Context: This error occurs when your API user doesn't have permission to access the requested resource. This can happen when trying to access a property or facility that isn't in your allowed list.

Handling: Verify that the resource ID is correct and that your API user has been granted access to it. Contact Facilitron support if you need access to additional resources.

404 Not Found: Resource Doesn't Exist

Code
 
{
  "message": "Property not found – The property with the specified ID does not exist.",
  "message_code": "PR001",
  "invocation_id": "c9949dff-f4cc-5377-cf08-28083b91452c"
}

Context: This error occurs when the requested resource (property, facility, or event) doesn't exist.

Handling: Verify that the resource ID is correct. If you're using IDs obtained from previous API calls, ensure your data is up to date.

429 Too Many Requests: Rate Limit Exceeded

Code
 
{
  "message": "Too Many Requests – Your account has exceeded the allowed number of requests.",
  "message_code": "SY006",
  "invocation_id": "c9949dff-f4cc-5377-cf08-28083b91452c"
}

Context: This error occurs when you've exceeded your API rate limit quota.

Handling: Implement exponential backoff logic and consider caching frequently accessed data to reduce API calls. If you regularly hit rate limits, contact Facilitron to discuss quota increases.

500 Internal Server Error: Server-Side Issue

Code
 
{
  "message": "Internal server error – An unexpected error occurred",
  "message_code": "SY004",
  "invocation_id": "d7456aef-01cd-5488-bf19-39194c02563d"
}

Context: This error occurs when an unexpected server-side issue prevents the request from being fulfilled.

Handling: Log the invocation_id and retry the request. If the error persists, contact Facilitron support with the invocation_id for further assistance.

503 Service Unavailable: Timeout

Code
 
{
  "message": "Timeout error – The operation timed out before completion.",
  "message_code": "SY003",
  "invocation_id": "e8567bff-12de-6599-cg20-40205d13674e"
}

Context: This error occurs when the operation times out before completion. This may happen with complex queries or during periods of high system load.

Handling: Try simplifying your request (e.g., smaller date ranges) or retry at a less busy time. Implement retry logic with exponential backoff.

Example Error Scenarios and Handling

Example 1: Invalid Date Range

Code
 
{
  "message": "The date range must not exceed one month (31 days)",
  "message_code": "SY001",
  "invocation_id": "a2727bfe-d9aa-4155-ae86-06871a90238a"
}

Handling: Adjust your start_date and end_date parameters to ensure they don't span more than 31 days and don't include dates in the past.

Example 2: Authentication Failure

Code
 
{
  "message": "Missing API key – The request is missing a required API key in the headers.",
  "message_code": "AU001",
  "invocation_id": "b8749cfe-d6bb-4266-9055-454ca2e51246"
}

Handling: Ensure your request includes the required Authorization header with Bearer YOUR_API_KEY.

Example 3: Resource Not Found

Code
 
{
  "message": "Property not found – The property with the specified ID does not exist.",
  "message_code": "PR001",
  "invocation_id": "c9949dff-f4cc-5377-cf08-28083b91452c"
}

Handling: Check that the property ID exists and your API user has access to it.

Example 4: Rate Limiting

Code
 
{
  "message": "Too Many Requests – Your account has exceeded the allowed number of requests.",
  "message_code": "SY006",
  "invocation_id": "c9949dff-f4cc-5377-cf08-28083b91452c"
}

Handling: Rate limit responses follow the HTTP Problem Details format. Implement exponential backoff logic and consider caching results to reduce API calls.

Example 5: Handling Lambda Cold Starts

If you receive occasional 503 errors that resolve on retry, you may be experiencing Lambda cold starts. This happens when a Lambda function hasn't been used recently and needs to be initialized.

Handling:

1. Implement retry logic with a 3-5 second delay
2. Keep your frequently used endpoints "warm" with periodic lightweight calls
3. Consider making API calls during business hours when Lambda functions are likely to be warm

Example 6: Exponential Backoff Implementation

Code
 
async function fetchWithRetry(url, options, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        // Rate limit exceeded - special case with simpler response structure
        const backoffTime = Math.pow(2, retries) * 1000; // Exponential backoff
        console.log(`Rate limit exceeded. Retrying after ${backoffTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, backoffTime));
        retries++;
        continue;
      }

      // For other error statuses, proceed with normal error handling
      if (!response.ok) {
        const errorData = await response.json();
        // Handle error with message_code and message
        console.error(`API Error: ${errorData.message_code} - ${errorData.message}`);
        // ... handle other error types ...
      }

      return response;
    } catch (error) {
      // Network error
      const backoffTime = Math.pow(2, retries) * 1000;
      console.log(`Network error. Retrying after ${backoffTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, backoffTime));
      retries++;
    }
  }

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

Need Help?

If you encounter persistent errors or need assistance, contact Facilitron API Support with the following information:

1. The HTTP status code
2. The complete error response including message_code and invocation_id
3. Details about your request (endpoint, parameters)
4. Date and time when the error occurred

For support, contact [email protected].