Request contract

GET /api/v1/portfolios/{portfolioId}/sync-status. Inspect the most recent synchronization status without repeating a provider call. Send the personal token in X-API-Key and keep it outside browser code and public logs.

Response and metering

The response separates balance refresh state from transaction backfill: it includes the available history start, guaranteed imported-through checkpoint, next run, retry count and safe provider-error classification. Successful metered responses publish X-Credit-Cost and X-Credits-Remaining so usage can be recorded without another request.

Production behavior

Use bounded polling with backoff and stop on terminal success or failure states. Handle application/problem+json errors by stable code, preserve the correlation ID and never retry a mutation unless the workflow is idempotent.