> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/digital-river-api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/digital-river-api-reference/digital-river-api-reference-guide/best-practices.md).

# Best practices

## API keys

When integrating with the Digital River API, you should know how to [use API keys](/digital-river-api-reference/digital-river-api-reference-guide/api-structure.md#api-keys) and [how they work with versioning](#versioning-and-keys).

## Versioning and keys

You should understand how your account's [API version](/digital-river-api-reference/digital-river-api-reference-guide/versioning.md) determines the requests an API allows and the responses generated. The version also determines the structure of events generated by API requests.

You should always configure your [API keys](/digital-river-api-reference/digital-river-api-reference-guide/api-structure.md#api-keys) to match the expected version of your code. In other words, when your code is deployed from test to production, the version on the keys should match the code version.

## Robustness

Digital River often makes [non-breaking changes](/digital-river-api-reference/digital-river-api-reference-guide/versioning.md#non-breaking-changes) to our API request and response content. As a result, we recommend your integration conform to the [tolerant reader](https://java-design-patterns.com/patterns/tolerant-reader/) principle. Specifically, this means that you should:

* Be aware that we can add new elements to responses at any time.
* Build your code to extract only the attributes needed when reading responses and ignore everything else.
* Avoid coding with a specific order of fields in mind.
* IDs are alphanumeric strings that potentially contain special characters and have variable lengths.
* Expect changes to the length and value of error messages and other strings that don't represent an enumeration, type, or code.
* Anticipate the addition of new optional request and query parameters.

## Dates and times

You should know how the Digital River API represents [dates and times](#dates-and-times) and ensure you properly format them in your requests.

## Fraud detection

When creating a checkout, invoice, or order, you should [provide an IP address](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-the-ip-address) to improve fraud detection.

## Call debugging and troubleshooting <a href="#call-debugging" id="call-debugging"></a>

To make call debugging easier, you should use specific [HTTP request headers](/digital-river-api-reference/digital-river-api-reference-guide/api-structure.md#headers-for-troubleshooting).

## Validation and conflict errors

Attempt to minimize HTTP `400 Bad Request` and `409 Conflict` [error types](/digital-river-api-reference/digital-river-api-reference.md#error-types) by adding appropriate validation checks before a request is submitted.

## Rate limiting

Our [request rate limits](/digital-river-api-reference/digital-river-api-reference-guide/rate-limiting.md) help ensure that the Digital River APIs are efficient, secure, and reliable. So, when building your integration, you should be aware of [the rate limits we impose](/digital-river-api-reference/digital-river-api-reference-guide/rate-limiting.md#our-approach-to-rate-limiting) and then implement automatic retry mechanisms that [handle rate limiting](/digital-river-api-reference/digital-river-api-reference-guide/rate-limiting.md#handling-rate-limiting). To avoid hitting the request ceiling entirely, follow our rate-limiting [best practices](/digital-river-api-reference/digital-river-api-reference-guide/best-practices.md).

## Transaction Speeds

* For HTTP `GET` requests, we encourage making concurrent calls.
* Avoid making changes to the same resource in multiple calls. Instead, bundle changes in a single call.
* Avoid making concurrent mutation calls to the same resource.

## Test Mode

You can use the `liveMode` flag contained in API responses to determine whether you're pointing to the correct [environment](/digital-river-api-reference/digital-river-api-reference-guide/api-structure.md#test-and-production-environments).

```javascript
}
   ...
   "liveMode": false
}
```

## Webhooks

* When using [webhooks](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks), check the [Digital River signature](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks/digital-river-signature) to ensure callback requests have not been tampered with.
* The webhook endpoint *must* be able to handle concurrent webhook callback requests.
* You may receive multiple duplicate webhook events. So, be sure you can process the delivery of duplicate events.
* Your webhook endpoint must respond to callback requests promptly. A response time greater than 3000 milliseconds is considered a timeout. We expect you to immediately acknowledge the callback request by sending an appropriate HTTP `2XX` response code. Once you acknowledge the callback, you can asynchronously process the webhook event on your end.