Internet Computer

How can my canister call a web API (HTTPS outcalls)?

All help topics

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.httpRequest from the ic package in Motoko, the HttpRequest::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_bytes caps 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 Host header 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.
Learn more
Still stuck? Contact support