Web app error reference

Carepatron's own web applications reach this API through a backend-for-frontend: it completes the OIDC sign-in, holds the tokens, and carries the session in a cookie rather than an API key. The refusals below are the ones that arrangement produces. They reach a signed-in browser application and never an integration holding an API key, whose failures are in the error reference.

A web app also receives the shared refusals either caller class can produce - unauthenticated, resource_not_found, rate_limit_exceeded, internal and the rest - which are documented on the error reference. The codes below are the ones only a web app can receive, not the whole set it can receive.

Every error is an RFC 9457 problem document (application/problem+json). Each type is https://developer.carepatron.com/docs/web-app-errors#{code} for one of the codes below, so a type you hold opens the entry describing it.

The code - the fragment at the end of that URI - is the stable, machine-readable identifier for the failure. Branch on the code, not on title or detail, which may be reworded, and not on the whole URI: the code is the part this contract holds immutable, the prefix is not. Read the fragment when there is one and the last path segment otherwise, and a prefix change cannot stop your handling firing.

A problem document also carries status, a human-readable title, an occurrence-specific detail, an instance trace identifier to quote when contacting support, and a timestamp. Quote instance when reporting a problem: it identifies the exact request.

400 Bad Request

api_key_already_revoked

API key already revoked

This API key has already been revoked; no further action is required.

web_app_csrf_validation_failed

CSRF validation failed

Send the X-CSRF header on every request: a fresh token from GET /auth/csrf on a state-changing request, and any non-empty value on any other. Sign in by navigating the page to /auth/login, not by loading it as a resource.

web_app_validation_failed

Invalid request path or field

Correct the invalid path segment or request field and resend; see the detail for the specific problem.

401 Unauthorized

web_app_authentication_required

Session authentication required

403 Forbidden

app_tenant_match_failed

App does not belong to the provider in the path

Check that the providerId in the request path matches the provider that owns this App.

paid_plan_required

A paid plan is required

Creating apps and API keys needs a paid Carepatron plan. Upgrade this workspace's subscription in Carepatron, then retry. Existing apps and keys can still be listed, revoked and deleted.

preview_docs_not_entitled

Preview documentation is not available to this account

The preview API reference is limited to workspaces enrolled in the preview programme. Ask your Carepatron contact about joining it; the released reference at the public documentation site needs no grant.

web_app_forbidden

Not permitted

Your session is valid but is not permitted to make this request. Signing in again will not change that.

web_app_identity_incomplete

Identity incomplete

Sign-in succeeded, but this account is not linked to a Carepatron user, so the application cannot tell who you are. Signing in again will not resolve it - contact Carepatron support.

web_app_provider_not_permitted

Caller not permitted for provider

Your user is not an admin of this provider. Contact your Carepatron administrator to be granted admin access before retrying.

web_app_user_identity_required

User identity required