# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalriver.com/digital-river-api-reference/digital-river-api-reference-guide/best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.