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:

{
  "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

{
  "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:

{
  "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