Third-Party API Integration Best Practices for AI-Built Apps

What calling a third-party API means

An API is the way one program asks another for something. A third-party API belongs to a service you don't run: a payment gateway, an email service, an address lookup, a text-message service or an AI model. Your app sends a request, and the service sends back a response. Our guide to what an API is covers the idea from the start.

When you build with AI, you usually test the call once, it works, and you move on. But every call to someone else's service can be slow, fail, or come back with something you didn't expect, and a quick demo never tries any of those. Most of this guide is about those other outcomes, because that's where real customers get double-charged or left staring at a spinner.

Should an API be called from the frontend or the backend?

Call it from the backend whenever it needs a secret key, which covers most services that cost money or act on your behalf. Your backend is a small function running on a server, and the browser never downloads its code. Anything in the frontend is sent to every visitor, so a key there stops being secret.

That includes the frontend's so-called environment variables: they're built into the files the browser downloads, whatever they're named. Our guide to why you can't put an API key in the frontend shows what a visitor can see and which keys are made to be public.

The backend is also the only place where you can control the call: set a time limit, decide what to retry, and log what happened. So even a call that doesn't need a secret is often better made there.

If your AI coding agent wires the call up in the browser anyway, the first sign is often a CORS error: the browser refusing to hand your page the answer from another web address. That's a browser security check doing its job, not something to switch off. The usual fix is to move the call to your backend. Our CORS error guide explains it.

What a signed request is, and when you need one

Most APIs only need your key sent along with each request, much like a password. Some, mostly payment gateways, also want a signature: a code your backend works out from the request's contents plus a secret only you and the service know. The service works out the same code from what it received. A match proves the request came from you and that nothing in it was changed on the way.

The recipe for that code (which fields, in what order, written in what way, hashed with which method) comes from the service's own documentation, and a single character out of place breaks it. The usual culprits are fields in the wrong order, spaces or punctuation written differently, blank fields left in when they should be dropped (or the other way round), capital letters where the service expects lower case, and a stray space or line break copied into the secret. AI coding agents often write the recipe from memory, so give yours the service's documentation for it.

The same check runs in the other direction. When a service calls you (a webhook), with a payment notification or an incoming chat message, it signs the request, and your backend checks the signature before it trusts anything inside. The pattern is always receive, check, then act. Many services also expect a quick reply and send the message again if they don't get one, so your backend should be ready to see the same message twice. Our guide to a webhook signature that won't verify covers that side in full.

What to do when an API call fails or times out

Besides success, a call can end three ways: no answer in time, a failed connection, or an error answer. The first two leave you not knowing whether the service did the work. An error answer comes with an HTTP status code (the short number a service sends back), and that code tells you what went wrong and what to do next.

Three habits follow from that table:

• Set a time limit. Without one, your backend can wait as long as the server lets it run, and the visitor watches a spinner the whole time. For something a person is waiting on, a few seconds is usually the most they'll tolerate.
• Retry with backoff, and stop. Backoff means waiting a little longer after each failed try, say one second, then two, then four, and giving up after a few tries. Adding a small random extra to each wait (called jitter) stops everyone's retries landing on the service at the same moment.
• Tell the user in plain words. "We couldn't confirm your payment with the payment service. Please don't pay again yet; we'll let you know as soon as we know whether it went through" beats a raw error or a page that never finishes loading. Never show them the service's raw error message; it can contain details they shouldn't see.

If a 401 appears only on the live site, the key usually wasn't set there. Our guide to environment variables that stop working after deploy covers why.

Is it safe to retry a failed API call?

Only if repeating it can't do the work twice. Reading something, such as looking up an address, is safe to retry. Creating or charging something, such as taking a payment, isn't safe on its own, because the first attempt may have worked and only the reply got lost. Those calls need an idempotency key or a check first.

The HTTP standard calls a request "idempotent" if "the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request". It also says a client "SHOULD NOT automatically retry" a request that isn't, unless it has some way to know the repeat is safe, or that the first attempt never went through.

The dangerous case is a timeout on a call from the last row. The payment may have gone through and only the reply got lost. A blind retry then charges the customer twice, and nothing in your app notices.

What an idempotency key is, and when you need one

An idempotency key is a unique reference your backend creates once for one action, such as one order, and sends with every attempt at that action. A service that supports these keys recognises the repeat and hands back the first result instead of acting again. Two rules make it work: every retry of the same action reuses the same key, and a genuinely new action gets a new one.

Not every API supports idempotency keys. The service's documentation will say, often under that name. If yours doesn't, your backend checks its own records before trying again: does this order already have a payment reference? Our guide to adding a payment gateway explains why your own records, updated from the gateway's signed notification, are the ones to trust.

Don't trust the response blindly

A reply from a service isn't automatically a useful one. Before your app uses it:

• Check it succeeded. An error reply still arrives as a reply. Code that only reads the data, without checking the status first, carries on with nothing.
• Check the parts you need are there. Services change their replies, and a missing field should produce a clear error, not a blank page or a price of zero.
• Treat it as data, never as code. Text from another service, including an AI model's output, shouldn't be dropped into your page as raw HTML or run as an instruction. Show it as plain text.
• Keep the reference. Store the service's own ID for each action (a payment reference, a message ID), so you can trace what happened later.

Keep keys and customer details out of your logs

Logs are how you find out what went wrong, and they tend to be read by more people and tools than your code is. Log the time, which service was called, the status code and the service's reference. Don't log the key, the hidden request details (headers) that carry it, or full customer details. Customer details in a log are still customer details you have to keep safe. If a key ever does end up in a log or in the browser, replace it with a new one at the service; deleting the log line doesn't un-publish it.

What isn't possible

• The browser can't hide a secret. There's no frontend-only way to use a secret key without publishing it.
• Retrying can't make a charge safe to repeat. Only an idempotency key, or a check against your own records, does that.
• You can't make someone else's service reliable. You can only decide what your app does when it isn't.
• Your AI doesn't know a service's current rules unless you show it. Field names, limits and signing recipes change. Give it the relevant part of the service's own documentation. It also can't see your live keys or your logs, so checking those is your job.

The prompt to give your AI

Copy this into your AI coding agent's chat. It asks for a plan before any code, so you can check the plan against this guide first.

I'm not a coder. I want my app to use [name of the
service] to [what it should do, e.g. take a payment /
look up an address / send a text message]. Here is the
relevant part of its documentation: [paste it or link
it]. Don't write any code yet. First give me a plan
that covers:

1. Where the call is made. If it needs a secret key,
   it must be a backend function, not the browser.
   Name the file, and show where the key is read from
   a stored secret.
2. The time limit on the call, and what the user sees
   if it runs out.
3. What happens for each outcome: a timeout, a 429,
   a 500-range error, a 400, a 401 or 403, and a
   failed connection. Say which ones are retried.
4. For retries: how many tries, how long between them,
   and whether a Retry-After header is respected.
5. Whether this call creates or charges something. If
   it does, how a retry is stopped from doing it twice
   (an idempotency key if the service supports one, or
   a check of my app's own records).
6. What in the response is checked before it is used.
7. What gets logged, with confirmation that the key
   and customer details never are.

If the documentation doesn't answer something, say so
instead of guessing.

What to check in the AI's answer

• The call is in a backend function. If the plan makes it from a page, a component or anything the browser loads, ask it to move the call.
• There's a real time limit. Look for an actual number. "Handles slow responses" isn't one.
• Not everything is retried. A 400, 401 or 403 should fail straight away, and retries should stop after a few tries.
• A payment or order can't happen twice. Ask it: "If the call times out and we retry, can the customer be charged twice?" The answer should name the idempotency key or the records check.
• The response is checked. The plan should say what happens when a field it needs is missing.
• The logs are clean. Ask it to list exactly what gets logged. The key shouldn't be on that list.

Test it before real customers do

Before launch, check where the key lives, then use the service's test (sandbox) mode to try the failures on purpose:

• Search for the key. Open your live site, view its source and the files it loads, and search for the start of your key. If you find it, the call is in the browser.
• Break the key. Set a wrong key in the test setup and trigger the call. You should see a clear error, not a spinner that never stops.
• Repeat an action. Trigger the same test order twice in quick succession, or ask your AI how to replay one. You should end up with one order, not two.

For a different service or a different job, the Custom Prompt Builder helps you write your own prompt from scratch, with the context and limits your AI needs.