ReferenceFor engineers

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 happensRecorded asBody
A 4th redirectthe redirect's own 3xx status{"error":"Refused: more than 3 redirects."}
A redirect to a URL that is not HTTPSthe redirect's own 3xx status{"error":"Refused: a redirect to a URL that is not https."}
A Location header that is not a usable URLthe redirect's own 3xx status{"error":"Refused: a redirect to an address that is not valid."}
A redirect to an internal address403{"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 headerReason
Idempotency-Key, X-Timestamp, X-Awell-SignatureAwell sets these on outgoing requests.
Host, Content-Length, Connection, Keep-Alive, Transfer-Encoding, TE, Trailer, UpgradeHTTP manages these per connection.
Any header whose name starts with Proxy-These instruct a proxy, not the endpoint.
Metadata-Flavor, X-Google-Metadata-RequestA 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-id
  • x-awell-care-flow-definition-id
  • x-awell-care-flow-start-date
  • x-awell-patient-id
  • x-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.

On this page