API call limits
Where an API call action is allowed to connect, how many redirects it follows, which headers Awell drops before sending, and how large a response it reads.
An API call action sends a request to an endpoint a care flow author typed in, so Awell limits where that request can go and how much of the answer it reads. This page lists each limit and the response recorded when one is hit.
A refused call is recorded against the API call activity the way a failure from the endpoint is: an HTTP status and a short JSON body. Retry settings apply to it, with the one exception noted below.
The endpoint must be HTTPS and publicly addressable
An endpoint that does not start with https:// is refused before anything is sent, and the call is
recorded as 400.
Awell also refuses to connect to an address that is not on the public internet: loopback and private ranges, link-local addresses such as the cloud metadata endpoints, and cluster-internal hostnames. The check runs against the endpoint before the request is built, and again at the moment each connection is made. A hostname that resolves to a public address on the first lookup and a private one on the second is refused at the second, and nothing is sent to it.
Either refusal is recorded as 403.
A redirect is followed three times, to HTTPS only
Awell follows a redirect itself rather than handing it to the HTTP client, so every hop gets the same address check as the endpoint. At most 3 redirects are followed.
| What happens | Recorded as | Body |
|---|---|---|
| A 4th redirect | the redirect's own 3xx status | {"error":"Refused: more than 3 redirects."} |
| A redirect to a URL that is not HTTPS | the redirect's own 3xx status | {"error":"Refused: a redirect to a URL that is not https."} |
A Location header that is not a usable URL | the redirect's own 3xx status | {"error":"Refused: a redirect to an address that is not valid."} |
| A redirect to an internal address | 403 | {"error":"Refused: the endpoint, or a redirect, leads to an internal address."} |
The method on a redirect follows the rules a browser uses. A 303 becomes a GET, unless the request
was a HEAD, and so does a 301 or a 302 after a POST. Every other combination keeps its method and
its body, so a redirected PUT or DELETE still arrives as a PUT or a DELETE.
Headers that Awell or HTTP sets are dropped before sending
A header configured on the action is dropped if its name is one Awell sets itself, one HTTP manages per connection, or one a cloud metadata server looks for. The comparison ignores case.
| Dropped header | Reason |
|---|---|
Idempotency-Key, X-Timestamp, X-Awell-Signature | Awell sets these on outgoing requests. |
Host, Content-Length, Connection, Keep-Alive, Transfer-Encoding, TE, Trailer, Upgrade | HTTP manages these per connection. |
Any header whose name starts with Proxy- | These instruct a proxy, not the endpoint. |
Metadata-Flavor, X-Google-Metadata-Request | A cloud metadata server requires one of these before it answers. |
The call is sent without them, and Awell logs each dropped header by name and never by value.
An endpoint that reads Idempotency-Key receives Awell's value, the id of the API call activity,
and not one configured on the action. See
Idempotent requests for its
format.
Configured headers reach the endpoint's host only
The headers configured on the action go to the host named in the endpoint and to no other. A
redirect to a different host, or to a different port on the same host, gets the request without
them, so an Authorization header is never handed to whoever a redirect names.
The care flow context headers Awell adds travel with the configured headers and stop at the same host:
x-awell-care-flow-idx-awell-care-flow-definition-idx-awell-care-flow-start-datex-awell-patient-idx-awell-tenant-id
Content-Type and the idempotency headers travel with the request wherever a redirect leads.
A response over 2.5 MB fails the call permanently
Awell reads at most 2,621,440 bytes, or 2.5 MB, of a response body. A larger response is not
recorded, so no data point mapping runs against it, and the call is recorded as 502 with the body
{"error":"The response was larger than 2.5 MB, and was not recorded."}.
The call is permanently failed and is never retried, whatever the retry settings say. The endpoint received the request and answered it, so sending the request again would produce the same answer.
An outgoing webhook has its own, smaller limit of 1 MB.
A call has 25 seconds to reach the final response
The 25 seconds cover the whole call up to the headers of the response that ends it, and each
redirect hop is given whatever is left. A call that runs out of time is recorded as 408.
A test call in Studio sends under the same limits
Testing an API call while designing the action uses the same sender, so the address rules, the redirect rules, the dropped headers and the 2.5 MB ceiling are the same as a live call's. A test call has a shorter time limit, and a test is never retried.
Next steps
Next: Configure API call retries: the settings that decide how often a refused call is tried again.
The API call action
Call any REST or GraphQL API from inside a care flow to fetch or send data, and store the response in data points the flow can build logic on.
Connecting to systems that require OAuth
Use two API call actions to fetch an OAuth access token and then call the real API with it, using the client credentials grant.