Solutions to common problems when calling external APIs from your Caffeine app.
My app isn't calling the external API from the backend — it's calling it from the frontend instead
This is usually the correct behavior, not a bug. The AI prefers frontend HTTP calls because they are faster and cost no ICP cycles. It only moves the call to the backend when it has to — for example, when an API key needs to stay secret or when the response must be stored in the app's backend.
If you specifically need the call in the backend, make that requirement explicit in your prompt: "Call this API from the backend and store the result in the canister" or "Keep the API key secret — it should never reach the browser."
The external API call is failing
If your app's backend is making a call that fails, there are a few common causes:
The URL is using plain HTTP instead of HTTPS. The ICP network requires HTTPS for outbound calls. If the API you are integrating with only supports HTTP, it cannot be called from the backend.
The API requires authentication that isn't configured. If the external service requires an API key or token in a request header, and that header isn't being sent, the call will fail with a 401 or 403. Ask the AI: "The API call is returning a 401 — add the API key to the Authorization header."
The external server is blocking the request. Some services block requests from ICP nodes. There is no guaranteed workaround for this — it depends on the external service's infrastructure and whether it accepts traffic from ICP subnet IP addresses. If you suspect this is happening, check whether the service has any restrictions on automated or non-browser traffic.
The API endpoint or response format has changed. If your app was previously working and stopped, the external API may have updated its URL structure or response format. Ask the AI to update the integration to match the current API documentation.
I can't read the response headers from the external API
This is a known limitation. HTTP outcalls on ICP strip all response headers before returning the response to your canister. Only the response status code and body are available. This is required to ensure all nodes in the subnet see a deterministic response.
If you need information that the external API provides only in headers (for example, rate limit data or pagination cursors), there may not be a workaround. Contact support if this is blocking an integration.
JSON parsing isn't working in the backend
Motoko, the language used for Caffeine app backends, does not have built-in JSON parsing support. When an external API returns JSON, the raw text is returned to the canister, but parsing it into structured data inside the canister is not straightforward.
The AI handles this by routing the raw JSON response to the frontend, where it can be parsed using standard JavaScript. If you're seeing errors related to JSON handling, describe the behavior to the AI and ask it to restructure how the response is processed: "The API returns JSON — handle the parsing on the frontend."
The app works in draft but the API call fails in production
Draft and live deployments run on the same ICP infrastructure, so the network-level behavior should be identical. If a call works in draft but not after going live, check:
- The URL is hardcoded to a staging or development endpoint. Ask the AI to switch to the production API URL.
- API credentials are different between environments. If you provided a test API key during development, the live app may need production credentials. Update those through the chat.
The call is very slow
Backend HTTP calls on ICP go through the subnet's consensus mechanism, which adds latency compared to a direct browser request. Typical response times are in the range of a few seconds. This is inherent to how ICP works and cannot be tuned.
If speed is critical for a particular integration, consider whether the call can move to the frontend instead. Ask the AI: "This API call is too slow from the backend — can it be moved to the frontend?"
The canister ran out of cycles because of HTTP calls
Each backend HTTP call consumes a fixed amount of ICP cycles. If your app makes a high volume of calls — for example, polling an external API frequently — the cycle cost accumulates. If the canister's cycle balance drops too low, calls will fail and eventually the canister will stop running.
Cycle management for deployed apps is handled by Caffeine's infrastructure for users on qualifying plans. If you are seeing cycle-related failures, contact support.
Something else is wrong with an external API integration
If an integration isn't working and none of the above applies, describe the problem in the chat with as much detail as possible — what API you're calling, what you expected to happen, and what error or behavior you're seeing instead. The AI can update the integration code accordingly.
For persistent issues that can't be resolved through the chat, contact support.