Troubleshooting

This section covers the most common integration issues when working with the Booking API.

API Key Requirements

The API key is associated with a user in the Podplay App.

To work correctly:

• The user must have the Admin role.
• The user must have a valid phone number assigned in their profile.

These conditions must be ensured by a Podplay Administrator in the Web Admin.

The administrator:

1. Creates the API key.
2. Assigns it to a valid admin user.
3. Shares it securely with the integrator.

Security Best Practice

• Store the API key securely.
• Use it only in your backend.
• Never expose it in frontend code (React, HTML, browser JavaScript).

Exposing the API key in frontend code is equivalent to making it public.

Low-Code / No-Code Platforms

If you are using a low-code platform (e.g. automation tools, workflow builders, internal dashboards):

• Use the platform’s Secrets, Environment Variables, or Secure Credentials section.
• Ensure the API key is marked as private or server-side only.
• Confirm it is not accessible from client-side scripts.
• Verify it is not logged or exposed in browser developer tools.

Most platforms provide a dedicated area for storing sensitive credentials — always use it.

Header Confusion — Use x-api-key

A common integration mistake is using the wrong authentication header.

Do not use:

Authorization: Bearer <token>

Instead, use:

x-api-key: <your-api-key>

The Booking API expects the x-api-key header.

To better understand the difference between API keys and Bearer tokens, see the following page:

API Keys vs Bearer Tokens

Pagination & Result Limits

Many collection endpoints support pagination using:

• page
• ipp (items per page)

Default and Maximum Values

For several core collection endpoints (such as Users, Orders, and Settlements):

• Default ipp: 30
• Maximum ipp: 100

If ipp is omitted, it usually defaults to 30.

If you request more than the allowed maximum (e.g. ipp=500), the value will be capped to the endpoint’s maximum (often 100).

Important: Not All Endpoints Share the Same Limits

Pagination behavior varies by endpoint.

Examples:

• Events (GET /events)

  • Maximum ipp: 1000 (or tenant-specific limit)
  • Default ipp: the maximum (e.g. 1000) if not provided
• Templates: default 25
• POS-related endpoints: default 50
• Coaches: default 500

Because limits differ, always verify the expected behavior for the specific endpoint you are using.

When to Adjust ipp

In many cases, the default ipp is sufficient.

If you are missing results:

1. Increase ipp (for example, to 100 where supported).
2. If the dataset is still larger than the maximum allowed per request, implement pagination using page and ipp.

Failing to paginate may result in incomplete data retrieval.

Learn More About Pagination

To see a practical example of how pagination works, refer to the following page:

Use Case: Retrieve Customer List

That page includes a concise use case demonstrating how to use page and ipp to retrieve a complete dataset.

Admission — "CLOSED"

When creating events via POST /bookings (using "type": "ORDER" with an eventSubtype), the value:

"admission": "CLOSED"

is only valid when:

"eventSubtype": "OPERATIONS"

If "CLOSED" is used with any other event subtype (such as "OPEN_PLAY" or "KIDS_CLASS"), the API will return a validation error (EB013).

Intended Use

"CLOSED" is designed for non-playable operational events, such as:

• Court maintenance
• Operational blocks
• Internal administrative reservations

These events are not meant to accept registrations.

Validation Errors (400 / 422)

If your payload is invalid, the API returns structured validation errors.

Below are common examples and how to resolve them:

Code	Message	How to Fix
EB017	User phone number is required.	The user associated with the API key must have a valid phone number in their profile. Update it in the app or via the User API.
EB018	Terms of Service agreement is required.	Send termsAgreed: true in the booking request body.

Recommendation

When debugging:

1. Log the full response body.
2. Check the error code.
3. Fix the specific field mentioned.
4. Retry with the corrected payload.

Integration Support

If an error message is unclear or the behavior does not match the documentation, the Podplay team can help troubleshoot.

To speed up the process, please provide:

• What you are trying to achieve (e.g. create an Open Play event)
• The endpoint you are calling (full URL)
• The request body (for POST/PUT requests)
• The full API response, including error codes and messages

This allows the team to:

• Identify validation issues
• Detect tenant-specific configuration constraints
• Confirm expected behavior
• Suggest the correct payload adjustments

Providing complete and structured information significantly reduces troubleshooting time.

When relevant, integration findings may also lead to documentation improvements — helping future integrators avoid similar issues.