# API Limits

The **gospace APIs** enforce limits to ensure performance, reliability, and fair usage across all services hosted at [https://api.gospace.app](https://api.gospace.app/). These limits cover usage quotas, request and response size restrictions, and timeouts. Below are the details for developers integrating with any **gospace API**.

### Usage Limits

Usage limits are applied per API key to manage the number of requests you can make across all gospace APIs within a specified time period. These limits help maintain service availability and prevent abuse. Exceeding these limits results in a 429 Too Many Requests response. Contact support at [support@gospace.com](mailto:support@gospace.com\)) to discuss higher quotas or custom plans.

| Limit Type          | Value                | Description                                                                     |
| ------------------- | -------------------- | ------------------------------------------------------------------------------- |
| Requests per Second | 100 requests/second  | Maximum number of API requests allowed per second per API key across all APIs.  |
| Requests per Day    | 100,000 requests/day | Maximum number of API requests allowed per day (24-hour period) per API key.    |
| Burst Limit         | 200 requests         | Maximum number of requests that can be made in a short burst before throttling. |

* Note: Usage limits reset daily at midnight UTC. If you require higher limits, please contact  <support@gospace.com> for a custom plan.

### Request Size Limits

The size of incoming requests (including headers, query parameters, and body) is limited to ensure efficient processing across all gospace APIs. Exceeding these limits results in a 413 Payload Too Large response.

| Parameter         | Limit | Description                                                                       |
| ----------------- | ----- | --------------------------------------------------------------------------------- |
| Request Body Size | 10 MB | Maximum size of the request body (e.g., JSON payload for POST or PUT requests).   |
| Query Parameters  | 10 KB | Maximum total size of query parameters (e.g., skip, limit, or filter parameters). |
| Headers           | 10 KB | Maximum total size of HTTP headers, including the x-api-key header.               |

* Example: For a POST request to create resources (e.g., { "connections": \[] } or { "teams": \[] }), ensure the JSON payload does not exceed 10 MB. Query parameters in GET requests (e.g., skip=0\&limit=25) must stay within 10 KB.

### Response Size Limits

The size of API responses is limited to ensure efficient data transfer. If a response exceeds these limits, it may be truncated, and a 413 Payload Too Large response will be returned.

| Parameter          | Limit | Description                                                                    |
| ------------------ | ----- | ------------------------------------------------------------------------------ |
| Response Body Size | 10 MB | Maximum size of the response body (e.g., JSON data returned by GET endpoints). |

* Example: For a GET request retrieving a list of resources (e.g., { "success": true, "data": { "connections": \[] } }), the response is limited to 10 MB. Use pagination parameters (skip, limit) to manage large result sets.

### Timeout Limits

API requests are subject to timeout limits to ensure timely responses and prevent resource exhaustion. If a request exceeds the timeout, a 504 Gateway Timeout response is returned.

| Parameter       | Limit      | Description                                                                  |
| --------------- | ---------- | ---------------------------------------------------------------------------- |
| Request Timeout | 30 seconds | Maximum time allowed for the API to process a request and return a response. |

* Example: Complex queries (e.g., filtering by entity type or ID) must complete within 30 seconds, or the request will time out.

### Best Practices

* Pagination: Use skip and limit query parameters in GET requests (e.g., GET /connections?skip=0\&limit=25) to retrieve large datasets incrementally and avoid exceeding response size limits.
* Batch Operations: Leverage bulk operations (e.g., POST /labels/mapping, PUT /connections) to create or update multiple resources in a single request, reducing the number of requests and staying within usage quotas.
* Optimise Payloads: Minimise the size of request bodies by including only necessary fields in objects like connection\_entity\_data or details.
* Rate Limiting Handling: Implement exponential backoff in your application to retry requests after receiving a 429 Too Many Requests response.
* Error Monitoring: Check the identifier field in error responses (e.g., "identifier": "bad\_request") to diagnose issues related to limits.

### Error Responses

Exceeding API limits results in the following HTTP status codes and error responses:

| Status Code | Description       | Example Response                                                                                                                 |
| ----------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 429         | Too Many Requests | { "success": false, "error": { "code": 429, "message": "Rate limit exceeded." }, "identifier": "rate\_limit\_exceeded" }         |
| 413         | Payload Too Large | { "success": false, "error": { "code": 413, "message": "Request or response too large." }, "identifier": "payload\_too\_large" } |
| 504         | Gateway Timeout   | { "success": false, "error": { "code": 504, "message": "Request timed out." }, "identifier": "request\_timeout" }                |

### Contact Support

If you need assistance with limits, require higher quotas, or encounter issues, contact our support team at <support@gospace.com>.