Errors

Handle an error by checking its HTTP status first. Error response bodies are endpoint-specific: do not assume that every failure returns the same JSON shape. The API reference lists the responses declared for each operation.

HTTP status codes

Status	Meaning	Recommended action
400 Bad Request	The request is malformed or violates input rules, such as an invalid range, parameter, body, or calendar type.	Correct the request before trying again. The body can contain field validation errors, plain text, or no content.
401 Unauthorized	One of the two required credentials is missing, invalid, or inactive.	Verify both authentication headers and replace invalid credentials. Do not retry unchanged credentials.
403 Forbidden	Authentication succeeded, but the Club API license, its resource capacity, or Club API Key permissions do not allow the operation.	Check that the club license is active, has sufficient capacity, and that the key has the required Read or ReadWrite access.
404 Not Found	The resource is absent or outside the club selected by the Club API Key.	Verify the resource ID and selected club. The API deliberately does not distinguish an absent resource from one belonging to another club.
409 Conflict	Current resource or domain state prevents the operation.	When the endpoint declares ApiErrorDTO, inspect ErrorType, refresh relevant state, and correct the operation before retrying.
429 Too Many Requests	The per-minute rate limit or the 30-day quota has been reached.	Do not retry immediately. Wait for the applicable window to reset and honor Retry-After when the header is present.
500 Internal Server Error	Uptivo could not complete the operation because of an internal error.	Retry a limited number of times with exponential backoff. For writes, verify the resulting resource state before retrying.
502 Bad Gateway	The webhook service returned an unexpected error.	Treat it as potentially temporary and retry with backoff.
503 Service Unavailable	The webhook service is temporarily unavailable, timed out, or throttled the request.	Retry with exponential backoff and jitter.

Rate limits

The Club API enforces both of these limits:

• 50 calls per minute;
• 25,000 calls per 30 days.

Responses include these rate-limit headers:

Header	Meaning
X-Ratelimit-Limit	The maximum number of calls allowed per minute.
X-Ratelimit-Remaining	The number of calls remaining before the current rate limit is exhausted.

When a limit is exceeded, the API returns 429 Too Many Requests. Stop sending requests instead of retrying immediately. Honor Retry-After when present; otherwise wait for the applicable minute or 30-day window to reset. Use bounded concurrency, cache stable data, and prefer webhooks over frequent polling.

Authentication failures

Every request requires both credentials:

X-Sub-Key: <subscription-key>
Authorization: Bearer <club-api-key>

An invalid Subscription Key is rejected by the public API gateway with this body:

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

A missing or invalid Club API Key also returns 401, but a response body is not guaranteed. A valid Club API Key with insufficient permissions, or one for a club without an active Club API license, returns 403.

See Authentication for the role and safe handling of each credential.

ApiErrorDTO

Selected application-level failures return a structured ApiErrorDTO. These can include 400, 403, 409, and 500 responses, depending on the operation:

{
  "ErrorType": "ClassFull",
  "Message": "Class is full for this booking \"Mode\""
}

• ErrorType is the machine-readable reason. Use it to select application behavior.
• Message is optional human-readable diagnostic text and can be omitted. Do not parse it or use it as a stable identifier.

Only expect this shape where the API reference declares ApiErrorDTO. Request validation errors can use a field-error object instead, and authorization failures can have no body. For example, webhook management conflicts can return 409 without ApiErrorDTO.

Public ErrorType values

The following values are currently returned by Club API operations.

Athlete creation and subscription conflicts

ErrorType	Meaning
InvalidData	Athlete account creation rejected the supplied data.
LicenseResourceLimitExceeded	The club license has reached its athlete capacity.
EmailAlreadyInUse	The requested email address is already assigned to another Uptivo account.
Internal	The operation failed internally; reconcile the resource state before retrying a write.
SubscriptionInUse	The UserSubscription cannot be deleted because it has active class bookings.

Class state and timing

ErrorType	Meaning
ClassNotPublished	The class is not published.
ClassNotBookable	The class booking mode does not allow booking.
Conflict	The athlete is already a participant, or concurrent state prevents the operation. Refresh the participant list before deciding what to do.
ClassFull	The selected attendance mode is full and queuing was disabled for the request.
ClassBookingIsEarly	The class is not yet visible for booking.
ClassBookingIsPastDue	The booking deadline has passed.
ClassHasStarted	The class has already started.
ClassIsFinished	The class has finished.
CancelTimeIsPastDue	The cancellation deadline has passed.

Athlete eligibility

ErrorType	Meaning
RequiredMedicalCertificate	The club requires a valid medical certificate for this booking.
RequiredMembership	The club requires a valid membership for this booking.
AthleteBookingDisabled	Booking is currently disabled for the athlete.
PoliciesNotAccepted	The athlete has not accepted the required purchase policies.

Payment and usage limits

ErrorType	Meaning
InvalidPaymentOption	The requested payment mode is unavailable or no valid automatic payment option exists.
NotEnoughCredits	The athlete does not have enough credits.
NoValidSubscriptions	No UserSubscription can pay for the class.
SubscriptionLimitsExceeded	Eligible subscriptions exist, but their weekly or monthly booking limits have been reached.
ClubLimitsExceeded	The club’s weekly or monthly participation limit has been reached.

Retry safely

• Do not automatically retry 400, 401, 403, or 404 without changing the request, credentials, permissions, or selected resource.
• Do not blindly retry 409. Read ErrorType when available and refresh the relevant resource before deciding whether another attempt makes sense.
• Retry network failures and 500, 502, or 503 only a limited number of times, using exponential backoff and random jitter.
• A timeout or 5xx response to a write does not prove that no change was made. Read the resource or otherwise reconcile state before repeating the write.
• Log the HTTP method, path, status, timestamp, and your own correlation ID. Never log either API credential.

If a persistent server error must be reported to Uptivo, include those safe diagnostic details and the response body, but never include the Subscription Key or Club API Key.