Reliability
Find the problem and the next step.
Start with the failing request’s status and response body. They tell you whether to fix the request, ask the editor to choose again, or retry later. Keep the request ID if you need help tracing it.
Problem Details
API errors return JSON with the content type application/problem+json. Use status and the code at the end of type in your handling logic. detail explains this particular failure; its wording can change.
{
"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 | Check the ID and environment. The record may also be hidden from this tenant. |
| 409 | conflict | Read detail. The session state or idempotency key conflicts with this request; do not retry it unchanged. |
| 410 | gone | The Picker session or temporary code is no longer usable. Start a fresh selection. |
| 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
For a timeout, temporary 5xx or 429, wait before retrying and increase the delay between attempts. Honour Retry-After if present and set an attempt limit.
If the response is uncertain, resend the same body and Idempotency-Key. Generate neither a new key nor a parallel redemption request.
400, 401, 403, 404, 409, 410 and 422. Correct state or request data first.
A timed-out write may already have succeeded. Only retry a write automatically when that operation documents idempotency. A new Picker session starts a new selection flow; it does not recover the result of an earlier redemption.
These API errors are separate from image-host responses. If a signed image URL has expired, ask your backend for a fresh URL and inspect any item-level denial. The image host may return 403, not an API Problem Details response.
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. |
| Picker selection count | A configured cap of 1–100, or 0 in multiple mode. Completion accepts at most 1,000 references; resolve and asset calls still need batches of 100. |
| Signed asset URL request lifetime | 60–3,600 seconds. |
| Picker redemption idempotency key | 191 characters. |
Troubleshoot by symptom
| What you see | Check first | What to change |
|---|---|---|
| Picker never opens | The CMS session request in the Network panel. | Fix login or CSRF errors, then check that the JSON contains data.session_id and data.picker_url. |
invalid_picker_origin | The launch URL and SDK pickerOrigin. | Use the same Test or Production origin for the backend API, SDK and Picker. Check protocol and port too. |
| Selection fails on confirmation | The CMS redeem response and its upstream request ID. | Check session ownership and expiry. For an uncertain network response, retry on the backend with the original idempotency key. |
| Expected artwork is missing | Search filters, current availability and credit-display support. | Resolve the ID from your backend. Keep credit_display false unless your product can actually show attribution. |
| Image loads the wrong version | The saved rendition and returned version_key. | Request the saved key explicitly; do not replace it with the response’s physical variant. |
| Batch returns 200 but an image is missing | Each resolve result’s status, or the asset response’s denied array. | Keep successful items and handle the failed item by its reason. Ask for a new selection if the rendition is unavailable. |
When asking for support, include the environment, endpoint, HTTP status, problem type and X-Request-ID. Leave out tokens, launch URLs, selection codes and signed URL query strings.