Understanding these core concepts will help you build robust integrations with the Pave API.
The API implements rate limiting to ensure consistent performance and reliability for all customers.
- 10 requests per second per API key
- Limits apply across all endpoints
- Quotas automatically refresh each second
When you exceed the rate limit, you'll receive a 429 Too Many Requests response:
{
"message": "Too many requests",
"statusCode": 429
}Best practice: Use exponential backoff when hitting rate limits to automatically retry requests with increasing delays.
All list endpoints support pagination to handle large datasets efficiently.
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 |
{
"data": [
{
"id": "mc_123456-abcd",
"name": "H1 Merit Cycle",
"status": "active"
},
// ... more items
],
"nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTEyLTE2VDIxOjU5OjAwLjAwMFoiLCJpZCI6Im1jXzEyMzQ1Ni1hYmNkIn0="
}Pagination best practices
- Always check for
nextCursorin the response to know if more pages exist nextCursorwill 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
The API uses standard HTTP status codes and provides detailed error messages to help you diagnose issues.
All errors follow a consistent structure:
{
"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"
}
]
}| 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 |