A canister calls external HTTPS APIs itself through the management canister's http_request, and on a cloud engine these outcalls are free.
How it works
- Replicated (default): every node of the subnet sends the same request, and they must agree on the response. A transform function on your canister strips what differs between nodes (timestamps, request ids, header order) so they can agree.
- Non-replicated (
is_replicated = false): one node sends the request. Use it for rate-limited APIs and requests that must not run twice, at the cost of trusting that node with the response. - Flexible (Rust only): several nodes each return their own response, and your code reconciles them.
On a cloud engine
- Write ordinary outcall code:
Call.httpRequestfrom theicpackage in Motoko, theHttpRequest::new(url)builder with.send()in Rust. The wrapper asks what the call costs, gets 0 on an engine and attaches nothing. Don't hardcode a fee. - Make outcalls from your own canister, never through the proxy canister: the transform must live on the canister that sends the request, and a proxied outcall pays real cycles from the proxy's balance.
- Every outcall mode is available.
Limits
- HTTPS only, to public addresses: plain HTTP, localhost and private IP ranges are refused.
max_response_bytescaps the response at up to 2,000,000 bytes, headers included. Always set it, leaving room for 1 to 2 KB of headers. Requests are capped the same way.- At most 64 headers, 8 KiB per header name or value, 48 KiB for all of them, and URLs up to 8,192 bytes.
- The remote server has 30 seconds to answer (
Timeout expired), and the subnet 60 seconds to produce a result (Canister http request timed out, usually worth a retry). - Some APIs need the
Hostheader set explicitly.
Common failures
No consensus could be reached. Replicas had different responses: the transform is missing or leaves something that differs between nodes, or the call went through the proxy.- In replicated mode a POST is sent once per node, and each node's request counts against the API's rate limit. Use an idempotency key, or non-replicated mode, for anything that must happen once.