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 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 shape, served as application/problem+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)

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.

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 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 [e-mail] with the request URL, response body, and timestamp.