Error Handling

The public API always returns the same envelope shape for both success and failure.

API Partners should treat the response envelope as the first parsing boundary. Successful responses return error: null. Failed responses return data: null plus a structured error object with a message, path, timestamp, and request identifier when available.

Standard error envelope

The code field mirrors the HTTP status. The error object contains the API Partner-facing message. The details field is nullable. For Full API Integration and other idempotent writes, branch on error.details.code (for example CONSENT_GRANT_REQUIRED, FLOW_ENDPOINT_MISMATCH, or QUESTIONNAIRE_VALIDATION_FAILED). Human-readable messages may change.

{
  "code": 403,
  "data": null,
  "error": {
    "message": "Missing required scope(s): write:orders",
    "details": null,
    "path": "/v1/orders",
    "timestamp": "2026-03-10T10:00:00.000Z",
    "request_id": "req_1234567890"
  }
}

Active Full API Integration idempotency is the exception: HTTP 202 returns the stable identifier in data.code. It is a success envelope, so read Retry-After, wait, and retry the exact same request.

{
  "code": 202,
  "data": {
    "status": "in_progress",
    "code": "IDEMPOTENCY_IN_PROGRESS",
    "retry_after_seconds": 7
  },
  "error": null
}

When an appointment form is not ready yet, use PHYSICIAN_ORDER_PENDING from the error details to keep monitoring the appointment and retry form retrieval only when the response permits it.

Retry guidance

For Full API Integration identity, consent, order, questionnaire, and schedule writes, retry 202 IDEMPOTENCY_IN_PROGRESS after Retry-After with the exact same Idempotency-Key and payload. Completed retries replay the exact stored status and body.
Retry 429 after the number of seconds in Retry-After.
For safe reads such as offering schedule retrieval, retry 503 and network or gateway timeouts with capped exponential backoff and jitter. Do not treat an empty available_dates array as a failure: it is a valid offering with no current preview availability. A 404 means the offering pair is not resolvable or is no longer accessible.
After a network timeout on a write, reuse the same Idempotency-Key and resend the identical payload. Do not generate a new key unless you are intentionally starting a different order, cancel, or reschedule attempt.
Do not retry 400, 401, or 403 without changing the request or credentials.

Customer-consent mode conflicts

Both customer-consent mode conflicts are corrective HTTP 409 responses, not transient failures. Read the stable code at error.details.code and correct the branch before retrying the original logical request.

CONSENT_GRANT_REQUIRED
The key is provisioned for the Fitnescity Health consent API. Finalize reusable consent and resend the original logical request with consent_grant_id.
CUSTOMER_CONSENT_NOT_REQUIRED
The key is not provisioned for the Fitnescity Health consent API. Do not retry the reusable consent call; follow the provisioned API Partner-provided consent PDF lifecycle when applicable.

Common status meanings

202 Accepted (Full API Integration idempotency)

The original Full API Integration write is still processing. This is a success envelope with data.code=IDEMPOTENCY_IN_PROGRESS and error=null. Wait for Retry-After, then resend the exact same Idempotency-Key and payload.

400 Bad Request

Validation failed for the query string, path, or request body. Fix the payload before retrying.

401 Unauthorized

The x-api-key header is missing, malformed, or invalid.

403 Forbidden

The API key is inactive, the API Partner account is suspended, or the key does not have the required scope for the route.

404 Not Found

The endpoint is disabled for the current deployment, or the referenced resource does not exist.

409 Conflict

Same idempotency key plus a different payload is a hard conflict. Full API Integration also uses 409 for stable details.code values such as FLOW_ENDPOINT_MISMATCH, CONSENT_GRANT_REQUIRED, CUSTOMER_CONSENT_NOT_REQUIRED, and questionnaire or scheduling conflicts. Fix the request according to details.code before retrying.

429 Too Many Requests

The request exceeded the per-key or per-IP limit for the current window. Retry after the number of seconds returned in Retry-After.

500 Internal Server Error

Unexpected server failure. Retry only if the operation is safe to retry, and include the request_id when contacting support.

503 Service Unavailable

A downstream dependency is temporarily unavailable. For schedule reads, retry with capped exponential backoff and jitter. A schedule 503 does not currently guarantee a Retry-After header.

request_id and support workflow

You may send an X-Request-Id header containing only A-Z, a-z, 0-9, ., _, :, and -, with a maximum length of 128 characters. A valid caller-provided value is echoed in the response X-Request-Id header and used as the response request_id. If the value is absent or invalid, the API generates one.

When the API returns a request_id, log it in your own system. That identifier is the fastest way for Fitnescity Health to trace a failed request across API logs and downstream systems.

If you need help diagnosing a failure, include the route, timestamp, request_id, and your expected outcome when contacting support@fitnescity.com.