This article contains optional advanced features and can be safely ignored.
Default Behavior: Automatic Mode#
To use the automatic mode, set the following header:Or simply omit the X-Async header.In automatic mode, the message is inserted into our system's internal queue with a default expiration of 5 minutes. However, the API will wait for a response for only 10 seconds. If the response arrives within 10 seconds, it becomes synchronous, but if it takes longer, the response is returned in asynchronous mode.Making multiple calls with the same nonce in automatic mode (default) is safe: if the server is very busy, you will initially receive an asynchronous response; however, once the message is processed, you will see a synchronous response.Thus, the implementation difference compared to synchronous mode is that if the API returns in asynchronous mode, you can retry the same call with the same nonce until the response becomes synchronous.In 99.9% of cases, when the server is operating normally without access peaks, the calls will be synchronous in automatic mode.Use this mode when you want to maintain a high timeout but do not care much about the result immediately. In the vast majority of cases, the response will be synchronous. If it is asynchronous, retry the same call with the same nonce until it becomes synchronous.Implementation difficulty: easy.
Sync / Async Modes#
For your convenience, our system offers three types of calls: synchronous, asynchronous, and automatic.By default, every call is set to "automatic" mode. If you have no implementation preference, simply leave the default setting. See below for the available modes, how, and when to use them.Synchronous Mode#
To force to use the synchronous mode, set the following header:The synchronous mode will always perform the action synchronously: the API places your action in the processing queue and waits for the result for a maximum of 10 seconds. The message inserted into our internal queue also has a maximum duration of 10 seconds. If the action cannot be processed within this period, the API will return an HTTP 503 error (service unavailable), and the message will likely be discarded and never processed.Use this mode when you want to quickly discard an action that is taking too long.Implementation difficulty: very easy.
{
"response": {
...
},
"async": false
}
Asynchronous Mode#
To force to use the asynchronous mode, set the following header:In asynchronous mode, the API places the action in the processing queue and immediately returns a confirmation of receipt without waiting for processing. The result of the action must be checked later through another request or will be sent to a callback configured by the client. The message timeout is 5 minutes by default, meaning the action must be processed within this period.Use this mode when real-time processing is not required, allowing greater flexibility and efficiency for actions that can be completed later.Implementation difficulty: medium.
{
"urlResponse" : "https://pix2depixapi.blob.core.windows.net/api-response/nonce"
"async": true,
"expiration": "2024-12-17T12:30:41.861Z"
}
