Skip to content

Troubleshooting

This page covers common issues and solutions when working with the Firstbeat Sports Cloud API.

Try API connection with our sample code

If you are experiencing problems e.g. with authentication, you can try our sample code to see if there is any issue with the credentials and try to isolate the issue.

Sessions are missing from the API

If you can see measurements but no sessions, this is expected behavior. Sessions must be created manually by coaches in the Firstbeat Sports platform. The API does not automatically generate sessions when measurements are uploaded.

Key points:

  • Measurements and sessions are separate entities
  • Only coaches can create sessions
  • A measurement can exist without being part of any session

Authentication Errors

Authentication errors are among the most common issues when starting with the API. All API requests (except registration) require both a valid JWT token and API key.

Common causes of authentication errors:

  • JWT token issues (401 Unauthorized)
    • Token not created correctly (check your signing process)
    • Token expired (JWT tokens are valid for only 5 minutes)
  • API key issues (403 Forbidden)
    • API key missing from x-api-key header
    • Incorrect API key value
  • Request issues (400 Bad Request, 401 Unauthorized or 404 Not Found)
    • Incorrect API URL or endpoint path
    • Wrong HTTP method (GET vs POST)

See our Getting Started guide for detailed authentication instructions.

Summary of the needed authentication

Authentication for Firstbeat Sports Cloud API endpoints follows these rules:

  • The /register endpoint requires no authentication.
  • The /api-key endpoint requires only a JWT Token in the Authorization header.
  • All other endpoints require both a JWT Token and an API key.

Payload too large

The API has a 6 MB response size limit to ensure optimal performance. When the limit would be exceeded, the API responds with 413 Response Too Large. This can happen with big queries, especially when:

  • Requesting session results with many athletes
  • Including multiple time series variables
  • Using format=list query parameter (uncompressed format)

Here are some ways to work around this:

  • Request only the time series variables you need
  • Split large queries into multiple smaller requests
  • Use format=binary query parameter to use compressed time series format
  • Add to your request Accept-Encoding header with any of values zstd, br, gzip, deflate.

I get HTTP Status Code X

Firstbeat Sports Cloud API uses conventional HTTP response codes to indicate the success or failure of an API request.

Summary of HTTP Status Codes

Code Code Summary
200 OK API call was successful.
202 Accepted Server started to process data. Please wait 5s and try again.
204 No Content Analysis failed, and results are not available.
401 Unauthorized Check your JWT token creation and expiration.
403 Forbidden Verify API key in x-api-key header.
404 Not Found Check the endpoint URL.
413 Response Too Large See Payload too large
429 Too Many Requests Rate limit exceeded
5xx Server Error Issue on our end. If problem persists, please Contact Cloud API support.

HTTP Status Code: 202 Accepted

Some analysis data is computed on-demand rather than stored persistently. When you request analysis results for older data (measurements, sessions, or laps), the server may need to process it first.

What to do:

  1. Wait 5-10 seconds for processing to complete
  2. Retry your request
  3. The second request should return 200 OK with the analysis results

Need More Help?

If these solutions don't resolve your issue, we're here to assist! Contact us at sports-cloud-api@firstbeat.com.

To help us assist you quickly, please include:

  • Your API consumer ID
  • The full API request (URL, headers, body)
  • The complete API response

See our Support section for more details.