Errors
JSON error bodies on `/api/v1` include a machine-readable code and human message; handle 401, 403, 404, 409, 413, and 429 consistently in clients.
Failed requests return JSON with at least:
{
"error": "Human-readable summary",
"code": "machine_readable_code"
}
Exact field names follow the API reference.
Common cases
| HTTP | Typical cause | Client action |
|---|---|---|
| 401 | Missing or invalid Bearer token | Re-authenticate (OAuth) or check PAT |
| 403 | Valid token but missing scope or resource access | Show consent/scopes error; do not retry blindly |
| 404 | Portfolio or media not found in workspace | Refresh portfolio list; verify ids |
| 409 | Conflict (duplicate idempotency replay with different body) | Use a new idempotency key or accept cached response |
| 413 | Payload too large | Reduce export size or use resumable upload when available |
| 429 | Rate limited | Back off and retry with jitter |
Client UX
Surface error / code in dialogs (Lightroom) or logs (scripts). Do not swallow API errors — users need actionable messages (scope missing, portfolio not found, storage limit).