This page provides guidance on common errors you may encounter when working with the Magicline Open API, along with steps to resolve them.
Error message: "Authentication failed. No api-key, wrong api-key or wrong header name."
- Missing
x-api-keyheader — The request does not include thex-api-keyheader. - Invalid API key — The key is incorrect, has been rotated, or the integration is deactivated.
- Wrong header name — Using a non-standard header name (e.g.
Authorization) instead ofx-api-key.
- Ensure your request includes the header
x-api-key: <your_api_key>. - Verify the API key matches the one provided when your integration was activated.
- Check that your integration has not been deactivated — a deactivated integration invalidates the key.
Error message: "Authorization failed. The caller has no privilege to the given resource."
This is the most common error category. There are several distinct causes:
Error code: errormessage.permission.denied
Your integration is assigned to a specific studio (organization unit). If you try to access entities belonging to a different studio, access will be denied — unless you have cross-studio access enabled.
How to resolve:
- Verify that the studio ID in your request matches the studio your integration is assigned to.
- Check your integration configuration in the Magicline backend.
Error code: errormessage.permission.denied
If you need to access data across multiple studios, your integration must have cross-studio access enabled. Note that not all endpoints support cross-studio access — refer to the API reference to check which operations are available in cross-studio mode.
How to resolve:
- Contact your Sport Alliance account manager to request a cross-studio integration.
- Ensure the cross-studio integration is active and properly configured.
Error code: errormessage.third.party.customer.access.disabled
Error message: "No consent of member to allow data access for third party services provided."
The member whose data you are trying to access has not consented to third-party data sharing. This is controlled by the member's individual data privacy settings.
How to resolve:
- This is expected behavior for most integrations. Your application should handle this error gracefully and inform the user that their data privacy settings prevent this action.
- The member can update their data privacy preferences by contacting the studio.
Error code: errormessage.permission.denied
When working with the Device API, the device must be explicitly linked to your integration.
How to resolve:
- Verify the device ID is correct.
- Ensure the device has been assigned to your integration in the Magicline backend.
Error message: "Access denied - rate limit is exceeded."
You have exceeded the allowed number of API calls within the rate limit window.
- Implement exponential backoff in your retry logic.
- Reduce the frequency of your API calls.
- Cache responses where appropriate to minimize redundant requests.
- Use webhooks to receive real-time notifications about data changes instead of polling. This drastically reduces the number of API calls needed and ensures you only fetch data that has actually changed.
- If you consistently hit rate limits, contact your account manager to discuss your usage pattern and potential limit adjustments.
The Magicline Open API implements an adaptive query throttling mechanism (QoS filter) to ensure system stability during periods of high database load. When the database is under heavy load, certain endpoints may temporarily return a 503 Service Unavailable response. This is a protective measure to maintain overall system performance and data integrity.
- Implement a retry strategy with exponential backoff. The system will automatically recover once the database load decreases.
- Avoid issuing large numbers of concurrent requests to the same endpoint.
- Narrow query parameters (e.g. reduce date ranges) to lower the database impact of individual requests.
Some endpoints may return error messages like "The value is too large" without clearly indicating which parameter is at fault. This is a known limitation — not all validation errors include the reference field that identifies the problematic parameter. Always refer to the API specification for required fields, allowed ranges, and correct formats.
Common pitfalls:
- Omitting required path or query parameters (e.g.
customerId). - Exceeding maximum values for range parameters like
daysAhead. - Sending unexpected combinations (e.g. a voucher code together with a referral code when only one is supported).
When creating trial offers, the duplicate check mode is configured per studio (typically set to EMAIL). If a customer with the same email already exists, the request will be rejected with a DUPLICATE_CUSTOMER error.
How to resolve:
- Check whether the customer already exists before creating a trial offer.
- Coordinate with the studio on their duplicate check configuration.
If you attempt an operation that requires scopes your integration does not have, you may receive a 403 error after the request has already been partially processed (e.g. payment was taken but the booking fails).
How to resolve:
- Review your assigned scopes and ensure they cover all operations in your workflow end-to-end.
- Refer to the Scopes documentation for a full list of available scopes and their associated endpoints.
Some endpoints that aggregate large datasets (e.g. GET /v1/classes/slots with broad date ranges) may time out under heavy load.
How to resolve:
- Narrow your query parameters — reduce date ranges or use pagination where available.
- Avoid fetching more data than needed in a single request.
- Cache responses locally to avoid repeated fetches of unchanged data.
- Use webhooks to be notified of changes instead of polling large datasets.
- Implement retry logic with exponential backoff for transient timeouts.
By default, error messages are returned in the studio's configured language (often German). To receive English error messages, include the Accept-Language: en header in your requests.
Webhooks are dispatched based on the event type subscription, not filtered by which partner caused the change. If you subscribe to a data privacy change event, you will receive notifications for all changes on that studio — not just those triggered by your application. Filter events on your side by checking the payload content.
There are two types of cross-studio benefit usage for integration benefits:
- Inclusive contingent — Always validated and consumed in the customer's home studio context, regardless of which studio the customer is currently visiting.
- Purchased contingent — If the inclusive contingent is exhausted, the system falls back to purchased contingents in the visiting studio, if the customer has previously purchased them there. A benefit can only be purchased in studios that have an integration benefit configured for it — either the integration's own studio or any whitelisted studio that also has the benefit in its integration.
If you receive a permission denied error when trying to use a benefit cross-studio, verify that the target studio has the benefit configured in its integration.
- Check the
errorCodefield — The response body contains a machine-readableerrorCodethat identifies the exact issue. Use this for programmatic error handling. - Inspect the
referencefield — Some error responses include areferencethat points to the specific field or resource causing the issue. - Use
Accept-Language: en— Include this header to receive English error messages instead of the studio's default language. - Validate your integration and scopes — Most 403 errors stem from integration misconfiguration. Verify your integration's studio assignment, scopes, and permissions.
- Use the correct environment — Ensure you are targeting the correct API base URL for your environment (sandbox vs. production).
- Implement retry logic — For transient errors (5xx, timeouts), use exponential backoff. For 4xx errors, fix the request before retrying.