Use each operation’s contract

API modules do not all use the same response envelope, success code or pagination fields. Use the relevant API reference as the contract. For example, Programmes lists use data with meta.nextCursor; Account operations may return a flat object.

Asynchronous work and eventual consistency

Some writes return 202 Accepted: the request has been accepted for processing, but the resulting record or downstream changes may not yet be available. Retain the response’s identifiers and follow the operation’s status/read workflow. Other writes complete synchronously and use 200 or 201.

List and search views may lag a successful write. Allow a bounded delay before retrying a read; do not repeatedly submit the create request because the new record is not immediately visible. Import jobs have their own status and error workflow.

Workspace scope

A tenant is a workspace, not the whole legal organisation. Most tenant-scoped endpoints require X-Tenant-Id; Account’s PAT and OAuth-client management operations carry the tenant in the URL. Use the operation’s documented parameters.

Authentication alone does not grant access. Current membership, action permissions and record-level restrictions still apply. A write permission does not generally include the matching read permission.

Errors and troubleshooting

Parse the HTTP status and then the body: the nested error.code/error.message envelope is common, but Account also returns string errors and gateways can return a message field. See Authentication for the distinction between invalid credentials and denied access.

When reporting an issue, include the endpoint, time, status, non-sensitive error body, and any request, event or correlation identifiers returned by that operation. Do not include bearer tokens, client secrets or personal data in a support report.