> For the complete documentation index, see [llms.txt](https://docs.podplay.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podplay.app/api/use-cases/use-case-create-a-1-hour-open-play-event/troubleshooting.md). # Troubleshooting ### 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 ``` Instead, use: ``` x-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: {% content-ref url="/pages/NMlVWQAiYAb0zjsRCz1l" %} [API Keys vs Bearer Tokens](/api/api-keys-vs-bearer-tokens.md) {% endcontent-ref %} ### 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: {% content-ref url="/pages/zpqXQeZIMjG6d9mal8WW" %} [Use Case: Retrieve Customer List](/api/use-cases/use-case-retrieve-your-full-customer-list.md) {% endcontent-ref %} 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podplay.app/api/use-cases/use-case-create-a-1-hour-open-play-event/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.