Errors & limits

The API uses JSON responses and includes a GOFA-generated x-request-id on authenticated requests. Keep that ID with your application logs and include it when contacting GOFA Support; do not send API keys or health data to Support.

Error envelope

Errors from the common API access boundary have this shape:

{
  "error": {
    "code": "<public-error-code>",
    "message": "<human-readable-message>",
    "requestId": "<GOFA-generated-request-id>"
  }
}

The Vital Scan handler's 404, per-session polling 429, and handler-level 500 responses contain error.message and error.requestId; those responses do not promise an error.code. The common access boundary can reject a request before the handler runs, with the coded responses listed below.

Public error codes

The product_not_available and invalid_request checks are specific to session creation. The authentication, entitlement, and rate-limit checks apply to all three public session operations.

Retry behavior

• Fix the request or credentials before retrying 400, 401, or 403.
• For 402, wait until the allowance resets or ask GOFA to update the workspace; repeating the request cannot create a session without a point.
• For 429, honor Retry-After and use exponential backoff. A GET that polls the same session too soon returns 429 with the number of seconds to wait.
• GET requests may be retried after a network failure or temporary 5xx, with bounded exponential backoff. Honor Retry-After if present and stop at a deadline rather than polling indefinitely.
• Do not automatically replay POST after a timeout, lost connection, malformed response, or 5xx. In particular, commit_outcome_unknown and vital_scan_creation_unavailable mean creation could not be confirmed. The session and charge may already exist even though your backend did not receive 201. A new POST is a new billable operation; neither the same userId nor an Idempotency-Key header deduplicates it.
• For an uncertain POST, retain the request time and GOFA request ID if received. If you have a session ID, read that session with GET. Otherwise ask GOFA Support to reconcile the outcome before creating another session. There is no public lookup by userId, and GET does not recover the secret hosted URL. Do not send keys, hosted URLs, or health data to Support.
• After an uncertain DELETE, GET can check whether the session is still accessible. Repeating DELETE can return 404 if it already succeeded; it does not refund or create a charge.

Rate-limit headers

Authenticated responses may include:

• ratelimit-limit — the workspace-configured requests-per-minute limit.
• ratelimit-remaining — the remaining requests in the current window.
• ratelimit-reset — the reset time as a Unix timestamp in seconds.
• Retry-After — how long to wait when a request is rejected for a retryable limit condition.

The exact requests-per-minute value is configured per workspace; do not hardcode a plan value in your client. GET and DELETE are not billable, but they still consume rate-limit capacity. In addition, a given session may be polled no more than once every five seconds.

These are separate limits. For example, five-second polling is 12 requests per minute, so it exceeds a workspace configured for 10 requests per minute even with only one session. Share one request budget across all keys, session polls, creates, and deletes in the workspace. See the bounded, single-session example in Quick Start.

Charging

A successful POST /api/v1/vital-scan/sessions response (201 Created) consumes one available point. GET and DELETE consume no points. A rejected request does not intentionally create a billable session. Deleting a session, letting it expire, or a user leaving the hosted flow does not refund the point used for its creation.