Request contract

PATCH /api/v1/portfolios/{portfolioId}/sync. Request a new provider read and update the stored normalized balance state. Send the personal token in X-API-Key and keep it outside browser code and public logs.

Response and metering

A successful response reports SYNCING after durable queueing and publishes cost and remaining-credit headers. Poll the status endpoint for completion. Successful metered responses publish X-Credit-Cost and X-Credits-Remaining so usage can be recorded without another request.

Production behavior

Do not run this endpoint in a tight polling loop. Provider rate limits and a ten-credit cost make explicit scheduling important. Handle application/problem+json errors by stable code, preserve the correlation ID and never retry a mutation unless the workflow is idempotent.