# 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.

<table><thead><tr><th width="137.8359375">Field</th><th width="110.609375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>A URI that identifies the problem type</td></tr><tr><td><code>title</code></td><td>string</td><td>A short, human-readable summary of the problem</td></tr><tr><td><code>status</code></td><td>integer</td><td>The HTTP status code</td></tr><tr><td><code>detail</code></td><td>string</td><td>A specific explanation of this occurrence of the problem</td></tr><tr><td><code>instance</code></td><td>string</td><td>The API path that generated the error</td></tr><tr><td><code>request_id</code></td><td>string</td><td>A unique identifier for the request, useful for support</td></tr></tbody></table>

```json
{
    "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:

<table><thead><tr><th width="134.20703125">Status Code</th><th width="184.55078125">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>200</code></td><td>OK</td><td>The request was successful</td></tr><tr><td><code>400</code></td><td>Bad Request</td><td>One or more request parameters are missing or invalid</td></tr><tr><td><code>401</code></td><td>Unauthorized</td><td>The Bearer token is missing or invalid</td></tr><tr><td><code>404</code></td><td>Not Found</td><td>The requested resource does not exist or is not accessible with your credentials</td></tr><tr><td><code>500</code></td><td>Internal Server Error</td><td>An unexpected error occurred on the Occuspace servers</td></tr></tbody></table>

### 400 Bad Request

{% hint style="warning" %}
**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.
{% endhint %}

```json
{
    "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

{% hint style="danger" %}
**Your Bearer token is missing or invalid.** Ensure the `Authorization` header is included in every request and that the token value is correct.
{% endhint %}

```json
{
    "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

{% hint style="warning" %}
**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.
{% endhint %}

```json
{
    "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

{% hint style="danger" %}
**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.
{% endhint %}

```json
{
    "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.