Error Handling

The Occuspace API uses standard HTTP status codes to indicate the success or failure of a request. All error responses follow the RFC 7807 Problem Details standard for consistent, machine-readable error information.

Error Response Format

Every error response returns a JSON object with the following fields, regardless of the type of error. The request_id field is particularly useful when contacting support as it allows the Occuspace team to trace the exact request in our systems.

Field	Type	Description
type	string	A URI that identifies the problem type
title	string	A short, human-readable summary of the problem
status	integer	The HTTP status code
detail	string	A specific explanation of this occurrence of the problem
instance	string	The API path that generated the error
request_id	string	A unique identifier for the request, useful for support

{
    "type": "https://api.occuspace.io/problems/not-found",
    "title": "Not Found",
    "status": 404,
    "detail": "Location 1560 not found or not accessible",
    "instance": "/v2/locations/1560",
    "request_id": "f1b8698f-b0e8-4fb9-82e1-ddf89029350c"
}

HTTP Status Codes

The following HTTP status codes are used by the Occuspace API:

Status Code	Name	Description
200	OK	The request was successful
400	Bad Request	One or more request parameters are missing or invalid
401	Unauthorized	The Bearer token is missing or invalid
404	Not Found	The requested resource does not exist or is not accessible with your credentials
500	Internal Server Error	An unexpected error occurred on the Occuspace servers

400 Bad Request

Check your request parameters. A 400 error means something in your request is invalid. The detail field will identify the specific parameter that caused the error and what the valid values are.

{
    "type": "https://api.occuspace.io/problems/bad-request",
    "title": "Bad Request",
    "status": 400,
    "detail": "Invalid interval: 'yearly'. Supported intervals for occupancy: daily, hourly, weekly, monthly, 60min, 30min, 15min",
    "instance": "/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-03&interval=yearly",
    "request_id": "a3c9512d-e4f7-4ab2-91c3-eef12084610b"
}

Common causes of a 400 error include: an unsupported interval value for the requested metric, an invalid start_date or end_date format (expected YYYY-MM-DD), or using start_hour_filter, end_hour_filter, or days_filter with an interval that does not support them.

401 Unauthorized

Your Bearer token is missing or invalid. Ensure the Authorization header is included in every request and that the token value is correct.

{
    "type": "https://api.occuspace.io/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Invalid API key",
    "instance": "/v2/locations",
    "request_id": "b2d8423e-f5a6-4bc3-82d2-cce23195721c"
}

If you believe your token is correct but are still receiving a 401, contact your Occuspace Customer Success Manager to verify that your token is active.

404 Not Found

The requested resource was not found. This can mean the resource does not exist, or that your API token does not have access to it. The detail field will identify the specific resource that could not be found.

{
    "type": "https://api.occuspace.io/problems/not-found",
    "title": "Not Found",
    "status": 404,
    "detail": "Location 1560 not found or not accessible",
    "instance": "/v2/locations/1560",
    "request_id": "d5f0645g-h7c8-6de5-04f4-eeg45317943e"
}

Verify that the location ID in your request is correct and that your API token has been granted access to that location. If you believe you should have access, contact your Occuspace Customer Success Manager.

500 Internal Server Error

An unexpected error occurred on the Occuspace servers. This is not caused by your request. Please retry the request after a short wait. If the error persists, contact Occuspace with your request_id so our team can investigate.

{
    "type": "https://api.occuspace.io/problems/internal-server-error",
    "title": "Internal Server Error",
    "status": 500,
    "detail": "An unexpected error occurred. Please try again later.",
    "instance": "/v2/locations/1559/occupancy",
    "request_id": "e6g1756h-i8d9-7ef6-15g5-ffh56428054f"
}

When contacting Occuspace about a 500 error, always include the request_id from the error response. This allows our team to locate the exact request in our logs and diagnose the issue quickly.