An AI API integration is not finished when the first request returns 200. It is finished when contracts, permissions, failures, retries and stored results behave predictably.
Treat the model as one component inside a controlled business transaction.
Write the contract before the prompt
Document endpoint, method, authentication, request schema, response schema, status codes, timeout, rate limits and version behaviour. Define which fields are required and which side owns each identifier.
A prompt is not an API contract. Validate model output against a strict schema before any downstream write.
Separate identity, authentication and authorisation
Use a dedicated service identity and the minimum scopes needed for the workflow. Keep read and write permissions separate; never give deletion because a read-and-update job might someday need it.
OWASP lists broken object-level authorisation and broken authentication among major API risks. Review access controls alongside the company-data protection guide.
Manage secrets outside content
Store tokens in a secret manager or protected runtime configuration, not in prompts, logs, Trello cards or source files. Rotate them, restrict who can retrieve them and ensure errors never echo credentials.
Do not send confidential data to a model unless the purpose, vendor terms, region, retention and access controls have been reviewed.
Make writes safe and repeatable
Use idempotency keys or a business transaction ID when a retry could create a duplicate. Confirm the resource after a write instead of assuming that the response body reflects durable storage.
For update endpoints, learn whether the method is partial or replaces the complete object. Read-before-write protects fields only when the API contract requires a full replacement.
- validate object ownership before access
- reject unknown fields when appropriate
- distinguish retryable and permanent errors
- cap retries and use backoff with jitter
- record the before and after state for important writes
Validate every boundary
Validate inbound files and URLs, model output, tool arguments, API responses and stored records. Allow-list destinations if the workflow can fetch remote resources; OWASP describes SSRF when an API accepts a user-controlled URL without proper validation.
For agent tools, follow human approval rules before irreversible or high-impact actions.
Design timeouts, fallback and reconciliation
Set separate connection and operation timeouts. A timeout creates uncertainty: the remote write may have succeeded even when the client received no response.
Before retrying an uncertain write, query by transaction ID or resource ID. Add a reconciliation job that compares intended and actual state.
Test the integration as a system
Apply the failure cases from pre-launch AI testing: invalid schemas, missing fields, expired tokens, rate limits, timeouts, duplicate events, partial responses and unauthorised objects.
Acceptance means the correct business state, not merely a successful HTTP exchange.
A real full-update API trap
In one API I use, PATCH is not implemented and PUT requires the complete article object. Sending only the changed status could erase other fields.
My sequence is read-before-write: GET the record, preserve every required field, change only the intended value, PUT the full object, GET it again and compare all 21 fields. I also exclude DELETE entirely even though the token technically permits it.
This is why integration safety comes from explicit method semantics and verification, not from a successful response alone.
Questions and answers
Should AI call the business API directly?
Usually through a controlled tool layer that validates arguments, permissions and policy. Do not give a model an unrestricted HTTP client.
When should a request be retried?
Only for defined transient errors, within a capped budget. An uncertain write must be reconciled before repeating.
What is idempotency?
It means repeating the same logical request does not create additional effects. Use a stable transaction key and enforce it server-side.
Is a 200 response enough?
No. Verify the durable stored state and the final business outcome.
What must be logged?
Request identity, contract version, policy decision, tool call, result, error, retry and material before/after state, without leaking secrets.
Operational worksheet
Before approval, put every control into a worksheet with an owner, evidence, threshold and next review date. A statement such as “monitor quality” is not actionable. “Operations owner reviews the material-correction rate each Monday and pauses the workflow above the agreed threshold” can be tested.
Link every control to a business consequence. If a schema failure can corrupt a customer record, specify containment and reconciliation. If a cost alert only indicates harmless seasonal volume, define the context that prevents false escalation.
Keep versions of prompts, schemas, policies, tools and external dependencies. A result without its configuration cannot be reproduced. Record exceptions and their expiry dates so that temporary workarounds do not become permanent invisible policy.
Finally, rehearse the human path. The named owner should be able to find the evidence, stop or restrict the workflow, move cases to fallback and explain the current state without asking the AI system to diagnose itself.