Response times for the orders API vary based on network conditions, request complexity, and the path a request takes through the Toast platform.
If your HTTP client uses a timeout (less than 30 seconds), it can stop waiting for a request that the Toast platform is still processing. The following sections describe what a timeout means, how to prevent duplicate orders, and how to configure your API client.
Your API client's timeout controls how long your client waits for a
response from the orders API. It does not control how long the Toast
platform works on a request. When your API client's timeout expires, your
API client stops waiting and reports an error. The Toast platform
continues processing the request it already received and a request that
times out for your integration can still succeed. For example, a
POST request to the /orders endpoint that times
out for your API client can still create an order in the Toast platform.
If you retry that request without a safeguard, you
could create the same order twice.
Set the connect and read timeouts in your HTTP client high enough that normal response times do not trigger a timeout.
Many HTTP client libraries use a default timeout of only a few seconds. The Toast orders API has a response time of up to 30 seconds. Configure your API client to allow for this before retrying a request that times out.
A timeout indicates you did not receive a response, not that the request failed. When a request times out:
-
Do not retry the request immediately. Determine the current state first.
-
For order creation with an
externalId, retry with the sameexternalId. The Toast platform does not create a duplicate order. -
Set a maximum number of attempts. Report an error in your own system when you reach it, rather than retrying without limit.
The orders API Order object includes an optional
externalId field. Use this field to prevent duplicate orders.
Generate the externalId value in your own system before
you send the request. Use the same value on every retry of that order. Do
not generate a new value when you retry.
When you include an externalId in a POST
request to the /orders endpoint, the Toast platform enforces
that the value is unique. If you send the same externalId
twice, the Toast platform does not create a second order.
For more information about external IDs, see External identifiers.
|
Note |
|
You can add an |