EVOLUTION-MANAGER
Edit File: RETRY.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Retry a request until it succeeds.</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for RETRY {httr}"><tr><td>RETRY {httr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Retry a request until it succeeds.</h2> <h3>Description</h3> <p>Safely retry a request until it succeeds, as defined by the <code>terminate_on</code> parameter, which by default means a response for which <code><a href="http_error.html">http_error()</a></code> is <code>FALSE</code>. Will also retry on error conditions raised by the underlying curl code, but if the last retry still raises one, <code>RETRY</code> will raise it again with <code><a href="../../base/html/stop.html">stop()</a></code>. It is designed to be kind to the server: after each failure randomly waits up to twice as long. (Technically it uses exponential backoff with jitter, using the approach outlined in <a href="https://www.awsarchitectureblog.com/2015/03/backoff.html">https://www.awsarchitectureblog.com/2015/03/backoff.html</a>.) If the server returns status code 429 and specifies a <code>retry-after</code> value, that value will be used instead, unless it's smaller than <code>pause_min</code>. </p> <h3>Usage</h3> <pre> RETRY( verb, url = NULL, config = list(), ..., body = NULL, encode = c("multipart", "form", "json", "raw"), times = 3, pause_base = 1, pause_cap = 60, pause_min = 1, handle = NULL, quiet = FALSE, terminate_on = NULL, terminate_on_success = TRUE ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>verb</code></td> <td> <p>Name of verb to use.</p> </td></tr> <tr valign="top"><td><code>url</code></td> <td> <p>the url of the page to retrieve</p> </td></tr> <tr valign="top"><td><code>config</code></td> <td> <p>Additional configuration settings such as http authentication (<code><a href="authenticate.html">authenticate()</a></code>), additional headers (<code><a href="add_headers.html">add_headers()</a></code>), cookies (<code><a href="set_cookies.html">set_cookies()</a></code>) etc. See <code><a href="config.html">config()</a></code> for full details and list of helpers.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>Further named parameters, such as <code>query</code>, <code>path</code>, etc, passed on to <code><a href="modify_url.html">modify_url()</a></code>. Unnamed parameters will be combined with <code><a href="config.html">config()</a></code>.</p> </td></tr> <tr valign="top"><td><code>body</code></td> <td> <p>One of the following: </p> <ul> <li> <p><code>FALSE</code>: No body. This is typically not used with <code>POST</code>, <code>PUT</code>, or <code>PATCH</code>, but can be useful if you need to send a bodyless request (like <code>GET</code>) with <code>VERB()</code>. </p> </li> <li> <p><code>NULL</code>: An empty body </p> </li> <li> <p><code>""</code>: A length 0 body </p> </li> <li> <p><code>upload_file("path/")</code>: The contents of a file. The mime type will be guessed from the extension, or can be supplied explicitly as the second argument to <code>upload_file()</code> </p> </li> <li><p> A character or raw vector: sent as is in body. Use <code><a href="content_type.html">content_type()</a></code> to tell the server what sort of data you are sending. </p> </li> <li><p> A named list: See details for encode. </p> </li></ul> </td></tr> <tr valign="top"><td><code>encode</code></td> <td> <p>If the body is a named list, how should it be encoded? Can be one of form (application/x-www-form-urlencoded), multipart, (multipart/form-data), or json (application/json). </p> <p>For "multipart", list elements can be strings or objects created by <code><a href="upload_file.html">upload_file()</a></code>. For "form", elements are coerced to strings and escaped, use <code>I()</code> to prevent double-escaping. For "json", parameters are automatically "unboxed" (i.e. length 1 vectors are converted to scalars). To preserve a length 1 vector as a vector, wrap in <code>I()</code>. For "raw", either a character or raw vector. You'll need to make sure to set the <code><a href="content_type.html">content_type()</a></code> yourself.</p> </td></tr> <tr valign="top"><td><code>times</code></td> <td> <p>Maximum number of requests to attempt.</p> </td></tr> <tr valign="top"><td><code>pause_base, pause_cap</code></td> <td> <p>This method uses exponential back-off with full jitter - this means that each request will randomly wait between 0 and <code>pause_base * 2 ^ attempt</code> seconds, up to a maximum of <code>pause_cap</code> seconds.</p> </td></tr> <tr valign="top"><td><code>pause_min</code></td> <td> <p>Minimum time to wait in the backoff; generally only necessary if you need pauses less than one second (which may not be kind to the server, use with caution!).</p> </td></tr> <tr valign="top"><td><code>handle</code></td> <td> <p>The handle to use with this request. If not supplied, will be retrieved and reused from the <code><a href="handle_pool.html">handle_pool()</a></code> based on the scheme, hostname and port of the url. By default <span class="pkg">httr</span> requests to the same scheme/host/port combo. This substantially reduces connection time, and ensures that cookies are maintained over multiple requests to the same host. See <code><a href="handle_pool.html">handle_pool()</a></code> for more details.</p> </td></tr> <tr valign="top"><td><code>quiet</code></td> <td> <p>If <code>FALSE</code>, will print a message displaying how long until the next request.</p> </td></tr> <tr valign="top"><td><code>terminate_on</code></td> <td> <p>Optional vector of numeric HTTP status codes that if found on the response will terminate the retry process. If <code>NULL</code>, will keep retrying while <code><a href="http_error.html">http_error()</a></code> is <code>TRUE</code> for the response.</p> </td></tr> <tr valign="top"><td><code>terminate_on_success</code></td> <td> <p>If <code>TRUE</code>, the default, this will automatically terminate when the request is successful, regardless of the value of <code>terminate_on</code>.</p> </td></tr> </table> <h3>Value</h3> <p>The last response. Note that if the request doesn't succeed after <code>times</code> times this will be a failed request, i.e. you still need to use <code><a href="stop_for_status.html">stop_for_status()</a></code>. </p> <h3>Examples</h3> <pre> # Succeeds straight away RETRY("GET", "http://httpbin.org/status/200") # Never succeeds RETRY("GET", "http://httpbin.org/status/500") ## Not run: # Invalid hostname generates curl error condition and is retried but eventually # raises an error condition. RETRY("GET", "http://invalidhostname/") ## End(Not run) </pre> <hr /><div style="text-align: center;">[Package <em>httr</em> version 1.4.2 <a href="00Index.html">Index</a>]</div> </body></html>