Handle connection errors

Use this guide when a proxy request or action stops working for a connection that used to work. It covers what each error means and what your backend should do.

Read the health first

GET /api/v1/connections/:id and GET /api/v1/connections return a derived health:

Health	Meaning	Your move
`healthy`	No unresolved refresh failure	Nothing
`refreshing`	A refresh lease is active right now	Retry shortly
`failing`	Last refresh failed; automatic retries continue once per UTC day	Watch, or prompt reauthorization
`needs_reauthorization`	Four failure days exhausted, or the token has no refresh token	Reauthorize

Health is computed from lifecycle facts, never stored, so it is always current. Filter with ?health=needs_reauthorization to find every connection that needs a user.

Map proxy and action errors

Proxy requests and actions share the same connection error responses.

Status	Body `error.code`	Cause	Your move
401	`connection_refresh_exhausted`	Refresh attempts exhausted	Reauthorize. Body carries `connectionId`.
409	`connection_refresh_backoff`	A refresh is in flight, or one failed under 30 seconds ago	Retry after `Retry-After` (1 second)
502	`connection_refresh_failed`	The provider rejected the refresh just now	Retry later; if it persists, reauthorize
404	plain `error` string	Wrong connection ID or wrong `X-User-Id`	Check ownership

Actions add their own codes. See HTTP API → Actions.

Reauthorize without losing the connection

Reauthorization replaces credentials in place. The connection keeps its ID and owner, so nothing in your database has to change.

Through the hosted page (recommended): mint a session for the existing connection instead of a user.

curl https://super-connect.dogar.biz/api/v1/connect/sessions -X POST \
  -H "Authorization: Bearer $SUPER_CONNECT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"connectionId":"CONNECTION_ID"}'

The session's owner and integration come from the connection and cannot be widened. Open the connectLink, or pass the token to openConnectUI. The page shows mode: "reauthorize".

Low-level handoff: POST /api/v1/connections/:id/reconnect returns a 30-minute, one-use OAuth URL. Use it only when you already control the browser flow.

A successful callback resets every refresh column and emits an auth webhook with operation: "override". A declined consent leaves the stored connection untouched.

Retry rules for `backoff`

connection_refresh_backoff is temporary by design:

Proxy requests wait up to 12 seconds for an in-flight refresh before answering 409.
A refresh failure holds the connection for 30 seconds before anything tries again.

Retry once after the Retry-After delay. If you still get 409, check health rather than looping.

Watch for it proactively