Skip to main content
Every Public API bearer error uses the error envelope documented on the contracts page: an error object with code (HTTP status), key (machine-readable key), message (human-readable text), optional details, and a meta.requestId. Match client logic on the exact error.key string, never on error.message. Messages may be reworded or translated; keys are stable. error.key values come in two families:
  • Framework keys are dotted lowercase (auth.invalid_token, rate_limit.exceeded). They cover authentication, scopes, rate limiting, idempotency, routing, and server errors. They can occur on any bearer endpoint.
  • Endpoint validation keys are UPPER_SNAKE (PUBLIC_API_INVALID_CLIENT_ID, CLIENT_NOT_FOUND). They are emitted by endpoint request validation and domain checks, so each key only occurs on the endpoints that use the underlying resource.

Framework keys

403 auth.provider_unavailable means Public API access is currently unavailable for the token’s company. Ask the company administrator or FITsociety support to check company access. An unexpired token cannot bypass this restriction; requesting another token does not restore disabled access.

Endpoint validation keys

Endpoint validation keys use UPPER_SNAKE. The tables below list every key the Public API can emit. Both PUBLIC_API_* keys and the domain keys in the second table are stable.

PUBLICAPI* keys

Domain keys

OAuth token endpoint errors

POST /public/v1/oauth/token does not use the bearer error envelope. It returns standard OAuth 2.0 (RFC 6749) error responses: See the authentication page for the token request and response shape.

Calendar query complexity

PUBLIC_API_CALENDAR_QUERY_TOO_COMPLEX returns HTTP 400 when computing a complete occurrence page would exceed the calendar work budget. Error details identify action: narrow_date_range_or_filters and the budget reason. Shorten the requested date range or add specific filters before retrying. This is independent of page size; requesting only ten items still requires a complete, correct occurrence set.