Response contracts and data handling

REST response envelopes

Status returns authentication and tenant metadata. Operation search returns operations, count, location identifier, and public key identifier. Operation description returns one typed contract. Direct execution returns the operation key, credential location, direct_read execution mode, and a structured result from the reviewed tenant adapter.

Error responses place a stable code and message inside the HTTP detail object. Clients should branch on the HTTP status and structured code, not on a full English message that may improve over time.

MCP response envelopes

Successful JSON-RPC responses contain jsonrpc, the matching request id, and result. Protocol failures contain an error object. A tools/call request can return a valid JSON-RPC result where the MCP tool payload has isError true, textual content, and a structuredContent error code and message.

Preserve request IDs in the client for correlation, but do not use customer identifiers or secret values as request IDs. Validate that a response ID matches the outstanding request before processing the result.

Cache and log controls

• Authenticated responses use Cache-Control: no-store, max-age=0.
• Do not place private responses in a shared CDN, browser cache, analytics event, or public error page.
• Redact Authorization headers before logs, traces, and support exports.
• Log operation keys and error codes instead of complete customer records.
• Restrict diagnostic access and apply a short operational retention period.
• Remove temporary debug logging immediately after the issue is resolved.

Downstream data responsibilities

A successful API response does not make every downstream use lawful or appropriate. The customer controls why the integration retrieves data, which destination receives it, who can access it, how long it remains, whether consent or notice is required, and how access, correction, export, suppression, legal hold, and deletion requests are completed.

Use field allowlists, encryption, access logging, regional and vendor review, retention enforcement, and deletion verification appropriate to the data. Avoid using API or MCP results for medical, legal, financial, employment, housing, credit, or other consequential decisions without the safeguards and human review required by applicable law.

Validate result shape and meaning

Check that the result is an object and that required fields have the documented types before updating a downstream system. Treat missing optional fields as unknown, not false or zero. Preserve source timestamps and identifiers needed for reconciliation, but do not store extra fields simply because they were returned.

A successful transport response does not guarantee that the source record is complete, current, or suitable for a business decision. Compare relevant timestamps, handle duplicates, identify partial pages or limits, and require human review when a missing or stale value could affect a person.