Reliability

Handle failures predictably.

Use the HTTP status for broad handling, the stable problem type for application logic, and the request ID for tracing and support.

Problem Details

API errors use application/problem+json:

400 responseJSON

{
  "type": "https://collection.vieunite.com/problems/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The cursor is invalid.",
  "request_id": "req_95afd55a160fbb748d1c69dc"
}

Every response also carries X-Request-ID. You may supply your own request ID header to connect Vieunite requests to CMS traces.

Error codes

Status	Problem code	Recommended handling
400	`invalid_request`	Fix parameters, cursor, origin or request semantics. Do not retry unchanged.
401	`unauthorized`	Check the environment, credential, expiry and revocation state.
403	`forbidden`	Check token type, scopes, plan, rights and origin.
404	`not_found`	Treat the resource as missing or not public to this tenant.
409	`conflict`	Stop automatic retries unless using the original idempotency key.
410	`gone`	Refresh the session, signed URL or capability instead of retrying it.
422	`validation_error`	Correct the request shape or field constraints.
429	`rate_limit_exceeded`	Apply bounded exponential backoff and jitter.
5xx	Server failure	Retry safe operations with backoff and retain the request ID.

Retry policy

Retry

Transient 5xx, network timeout and 429 responses after waiting. Keep a strict attempt and elapsed-time budget.

Retry with the same key

Picker redemption after an uncertain response. Reuse the exact Idempotency-Key.

Do not retry unchanged

400, 401, 403, 404, 409, 410 and 422. Correct state or request data first.

Never retry by creating multiple simultaneous Picker sessions or by exchanging one-time capabilities in parallel.

Important limits

Area	Limit
Common page size	1–100 items; endpoint defaults vary.
Batch catalogue request	100 IDs.
Reference resolve or validate	100 references.
Signed asset request	100 requested artwork items.
Picker session lifetime	60–900 seconds.
Signed asset URL request lifetime	60–3,600 seconds.
Picker redemption idempotency key	191 characters.

Troubleshooting checklist

1
Record the HTTP status, problem code and X-Request-ID.
2
Confirm the request uses the expected test or live base URL.
3
Check credential expiry, revocation and required operation scope.
4
For Picker issues, confirm the registered exact origin and CMS session ownership.
5
For unavailable artwork, resolve or validate the reference and inspect its item-level reason.