Pagination and errors

Inspect both transport status and the operation result. A successful request does not imply that every batch row succeeded.

Profile pagination

GET /api/v1/profiles supports page, limit and cursor plus filters. The schema permits limit 1–1000; the CLI profiles command deliberately accepts 1–100 and defaults to 100. Use pinned_first=false for cursor traversal. Keep sort, order and filters unchanged, pass the returned next_cursor verbatim and stop when it is null. Cursors cannot be combined with pinned_first=true. Page/offset lists can shift while profiles are edited; this is not a transactional snapshot.

HTTP

GET /api/v1/profiles?limit=100&pinned_first=false
GET /api/v1/profiles?limit=100&pinned_first=false&cursor=<NEXT_CURSOR>

URL-encode query values. Other route families have their own pagination schemas. Transfer list uses next with page or cursor depending on the provider; it does not use the native profile cursor.

Native error envelope

JSON

{
  "error": {
    "code": "auth.scope_missing",
    "message": "Berechtigung fehlt",
    "details": {
      "missing": [
        "profiles:read"
      ]
    }
  },
  "request_id": "example-request-id"
}

This is a fictional structural example. Branch on error.code and status rather than localized message text. Keep request_id for correlation, but remove credentials and personal data from reports. Batch endpoints can return individual failures in a successful HTTP response: inspect results and failure counts.

Status handling

HTTP	Meaning and action
400	Invalid fields or state-dependent validation. Compare the exact schema and error details.
401	Missing, expired, revoked or invalid token. Correct the local credential.
403	Missing scope or forbidden browser origin. Do not bypass the boundary.
404	Unknown route/resource or unavailable transfer preview. Verify the installed version and ID.
409	Conflict with current state. Re-read state before retrying.
413 / 415	Payload too large / Content-Type must be application/json.
421	Host header is not an allowed local address and port.
429	Throttling or operation capacity. Respect Retry-After if present.
5xx	Service/provider failure. Record the safe error code and verify resulting state.

Timeouts and retries

A timeout or lost response does not roll back an operation. After a start, create, import or execute request, inspect the resulting state before retrying. There is no universal idempotency-key contract in this export. Native request bodies default to 1 MiB; selected import/batch routes have larger limits. Do not assume the larger limit applies to every route. Twenty failed local authentications within one minute trigger a one-minute block for that client IP.