> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collectpure.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Best practices for integrating with the Pure API

This guide provides best practices and recommendations for developers integrating with the Pure API.

## Rate Limiting

While we don't publish specific rate limits, we do monitor API usage to ensure fair access for all users. If you're planning to make a large number of requests, please contact us at [support@collectpure.com](mailto:support@collectpure.com) to discuss your needs.

## Error Handling

The API returns standard HTTP status codes to indicate success or failure:

* **200 OK**: The request was successful
* **400 Bad Request**: The request was invalid or improperly formatted
* **401 Unauthorized**: Authentication failed (invalid or missing API key)
* **404 Not Found**: The requested resource was not found
* **500 Internal Server Error**: An unexpected error occurred on the server

All error responses include an `error` field with a description of what went wrong:

```json theme={null}
{
  "error": "Detailed error message"
}
```

## Pagination

For endpoints that return multiple items, we use offset-based pagination:

```
GET /products/search/v1?offset=0&limit=10
```

* **offset**: Number of items to skip (default: 0)
* **limit**: Maximum number of items to return (varies by endpoint)

The `/products/search/v1` endpoint supports browsing all products without a search query. Simply omit the `query` parameter to paginate through the full product catalog. This endpoint supports up to 250 results per page:

```
GET /products/search/v1?limit=20
```

Order endpoints (`/orders/get-sale-orders/v1`, `/orders/get-purchase-orders/v1`) also support offset-based pagination with a default of 20 and a maximum of 100 results per page.

## Handling Spot Prices

Spot prices for precious metals can change rapidly. When displaying spot prices to users, consider:

1. Showing the timestamp (`updatedAt`) to indicate when the price was last updated
2. Implementing a refresh mechanism to fetch updated prices periodically
3. Displaying the market status (`marketOpen`) to indicate if the market is currently active

## Working with Product Data

When working with product data, keep in mind:

1. Products may have multiple variants with different pricing
2. The `highestOffer` and `lowestListing` fields represent the current market state and may be null if no offers/listings exist
3. Premium calculations can vary by product subcategory (check the `premiumCalculationType` field)

## Testing

We recommend testing your integration thoroughly before deploying to production. Use the following approach:

1. Start with the `/protected` endpoint to verify authentication
2. Test with a small subset of products before implementing full integration
3. Implement proper error handling for all API calls
4. Consider implementing retry logic for transient errors

## Support

If you encounter any issues or have questions about the API, please contact our support team at [support@collectpure.com](mailto:support@collectpure.com).