API reference

Errors

Every error has a stable code you can branch on, a message written for people, and a request ID for support. Messages can change; codes don't.

Error shape

{
  "code": "rate_limit_exceeded",
  "message": "This app has used its request limit; retry after 412 seconds.",
  "request_id": "req_0123456789abcdef0123456789abcdef",
  "details": {
    "scope": "app",
    "per_15_minutes": 100,
    "per_day": 10000,
    "per_athlete_per_15_minutes": 30,
    "per_athlete_per_day": 2000
  }
}

Branch on code and the HTTP status. Show message to a developer, not to an athlete. details appears on a few codes: validation_failed lists fields, rate_limit_exceeded gives the limits and scope, app_limit_reached gives max_apps, invalid_scope gives supported_scopes.

Bearer failures also send a WWW-Authenticate header: error="invalid_token" for 401, and error="insufficient_scope", scope="..." for 403.

Callback errors

If the athlete declines, your callback receives error=access_denied and your state instead of a code. It isn't a failure of your app: show them what they'd get and a way to try again. Problems with the authorize link itself never reach your callback; CorrConnect shows the athlete the error instead, with one of the /oauth/authorize codes below.

API errors

Everything except the token endpoint answers with code, message, request_id and sometimes details. invalid_client appears in both shapes: as code on the authorize page and as error from the token endpoint.

OAuth token errors

These come back from POST /oauth/token in the OAuth shape: error, error_description and request_id.

CorrConnect's own pages

The portal, sign-in recovery and device-connection screens use these codes. Your app does not call those routes, but an athlete may mention them in a support request.