> For the complete documentation index, see [llms.txt](https://knowledgebase.flaik.com/flaik-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/overview/error-handling.md). # Error Handling ## Overview flaik Connect uses standard HTTP status codes to signal failure. The response body carries a machine-readable error detail you can log and surface to your operators. This page is the shared reference for status codes, response shape, and retry guidance. Endpoint pages link here rather than repeating the contract. ## Status Codes | Status | Meaning | When you'll see it | | ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Success | Successful request. Body contains the response payload. | | `204` | No content | Successful request, no result to return (e.g. a search that found nothing). | | `400` | Bad request | The request was malformed, failed validation, or referenced a resource that doesn't exist for your resort. Body explains what went wrong. | | `401` | Unauthorized | Access token missing, expired, or invalid. See the [Authentication](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/overview/authentication) page. | | `403` | Forbidden | Token is valid but does not include a scope the endpoint requires (e.g. calling a write endpoint with a read-only token). | | `404` | Not found | Endpoint path doesn't exist, or a resource lookup explicitly raised a "not found" condition. | | `406` | Not acceptable | Server determined the request can be parsed but can't be satisfied (rare). | | `5xx` | Server error | An unexpected error on flaik's side. Safe to retry after backoff. | ## Response Body Error responses use the [RFC 7807 `ProblemDetails`](https://datatracker.ietf.org/doc/html/rfc7807) shape, served as `application/problem+json`: ```json { "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "Bad Request", "status": 400, "detail": "Season 999 does not exist for this resort.", "instance": null } ``` | Field | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------- | | `type` | string | URI reference to the problem type (often a generic RFC link) | | `title` | string | Short human-readable summary | | `status` | integer | The HTTP status code, repeated in the body | | `detail` | string | Specific explanation of this occurrence — the most useful field to log | | `instance` | string | URI reference identifying the specific occurrence (often `null`) | {% hint style="info" %} What to log: the `status` and `detail` fields together give you everything you need to act on the error. `detail` is the field human operators should see surfaced in your UI/logs. {% endhint %} ## Retry Guidance | Status | Retry? | Notes | | --------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------- | | `200/204` | n/a — success | | | `400` | **No** — fix the request first | Same request will fail the same way until you change it. | | `401` | After fetching a fresh token | Tokens expire after 1 hour. Re-fetch via `/connect/token` and retry. | | `403` | **No** — request a token with right scopes | Your token is missing the scope this endpoint needs. Coordinate with Flaik to update credentials. | | `404` | **No** — the resource doesn't exist | If a path you expect to exist returns 404, double-check the URL and IDs. | | `406` | **No** | Rare; see `detail`. | | `5xx` | Yes — with exponential backoff | Suggested: 1s, 2s, 4s, 8s, then alert. | ## Idempotency * **Read endpoints** (`GET`) — idempotent by definition. Safe to retry. * **`POST /api/employee/upsert`** — submission is **not** idempotent on the request body alone. Each call queues a new processing run. If you receive a 5xx after a submit, poll the [Upsert Status](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/employee-management/upsert-status) endpoint with any request id you've already received before retrying, to avoid double-queueing. * **`POST /api/employee/search`** — idempotent (no state change). Safe to retry. ## Common Errors by Endpoint Each endpoint page lists the specific `detail` strings it can return. The cross-cutting ones to know about: | `detail` (or equivalent) | What it means | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `"Season {id} does not exist for this resort."` | The `seasonId` you passed isn't configured for the resort your token belongs to. | | `"updatedAfterUtcDateTime is required."` | A delta-pull endpoint (e.g. shifts/delta, tasks/delta) was called without the timestamp. | | `"The specified date range must be less than or equal to 5 days in duration"` | Class management date-range exceeded the 5-day cap. | | `"Provided upsertEmployeeRequestId not found"` | The id you're polling for upsert status isn't recognised for this resort. | Need help interpreting a specific error? Contact with the request URL, response body, and timestamp. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/overview/error-handling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.