# Core concepts

Understanding these core concepts will help you build robust integrations with the Pave API.

## Rate limiting

The API implements rate limiting to ensure consistent performance and reliability for all customers.

### Current limits

- 10 requests per second per API key
- Limits apply across all endpoints
- Quotas automatically refresh each second


### Handling rate limits

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:


```json
{
  "message": "Too many requests",
  "statusCode": 429
}
```

**Best practice**: Use exponential backoff when hitting rate limits to automatically retry requests with increasing delays.

## Pagination

All list endpoints support pagination to handle large datasets efficiently.

### Pagination parameters


```
GET /v1/compensationPlanning/meritCycles?limit=50&nextCursor=eyJjcmVhdGVkQXQiOiIyMDI0LTEyLTE2VDIxOjU5OjAwLjAwMFoiLCJpZCI6Im1jXzEyMzQ1Ni1hYmNkIn0=
```

| Parameter | Type | Description | Default | Max |
|  --- | --- | --- | --- | --- |
| `limit` | integer | Items per page | 25 | 100 |
| `nextCursor` | string | Cursor for requested page | null | - 
 |


### Pagination response format


```json
{
  "data": [
    {
      "id": "mc_123456-abcd",
      "name": "H1 Merit Cycle",
      "status": "active"
    },
    // ... more items
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTEyLTE2VDIxOjU5OjAwLjAwMFoiLCJpZCI6Im1jXzEyMzQ1Ni1hYmNkIn0="
}
```

**Pagination best practices**

- Always check for `nextCursor` in the response to know if more pages exist
- `nextCursor` will be null on the last page
- Use a reasonable `limit` (max 100) to balance performance and number of requests
- Implement proper error handling for network issues during pagination


## Error handling

The API uses standard HTTP status codes and provides detailed error messages to help you diagnose issues.

### Error response format

All errors follow a consistent structure:


```json
{
  "timestamp": "2025-04-09T19:47:09.731Z",
  "path": "/v1/compensationPlanning/meritCycles/11231",
  "message": "Validation failed",
  "statusCode": 422,
  "validationErrors": [
    {
      "path": "limit",
      "message": "Number must be less than or equal to 100",
      "code": "too_big"
    }
  ]
}
```

### Common error codes

| Status code | Meaning | Common causes |
|  --- | --- | --- |
| `400` | Bad Request | Invalid request format or parameters |
| `401` | Unauthorized | Missing or invalid API key |
| `404` | Not Found | Resource doesn't exist or no access |
| `422` | Unprocessable Entity | Validation errors |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Internal Server Error | Server-side issue |