Errors

An error is JSON with the HTTP status, a machine-readable code and a message. Make decisions in your code by code: it is stable, while messages may change.

Response format

401 · application/json

{
  "status": 401,
  "code": "API_KEY_EXPIRED",
  "message": "Срок действия ключа истёк. Создай новый ключ или подключи приложение заново.",
  "requestId": "0d2c6f3a-9b1e-4c7d-8a5f-3e2b1c0d9e8f"
}

status: the HTTP status.
code: the machine-readable code. For a code you don’t know, go by the status.
message: a Russian fallback text; localize by code.
requestId: the same as the X-Request-ID header; you can send it to support.
params: safe details of some codes: scope, limitBytes, quotaBytes and usedBytes, retryAfter, feature.
currentRevision: only with PASTE_REVISION_CONFLICT.

When to retry

429 and 503 with Retry-After: wait that many seconds and retry.
409 with Retry-After on upload: an earlier attempt is still running; retry with the same Idempotency-Key.
A network error on upload: retry with the same Idempotency-Key; there will be no duplicate.
401 API_KEY_EXPIRED and API_KEY_REVOKED: retrying won’t help; you need a new key.

Common to all methods

Any method with a key may answer with an invalid or expired key (401), a missing permission (403 SCOPE_REQUIRED), invalid fields (400), too many requests (429) or an unavailable service (503). Method pages list only their own codes.

Codes

Code	Status	Message
`DEVICE_AUTH_INVALID`	400	The connection code is invalid or has expired. Start connecting again in the app.
`FOLDER_ARCHIVE_INVALID`	400	The folder archive could not be read: send a plain ZIP without a password, with UTF-8 names and no paths like “../”.
`FOLDER_EMPTY`	400	No files are left to share: dependencies, build output, secrets and non-text files are not uploaded.
`INVALID_JSON`	400	The request contains invalid JSON.
`LINK_EXPIRY_INVALID`	400	Pick a date and time at least 5 minutes and at most 10 years ahead.
`ONE_TIME_NOT_PUBLIC`	400	A one-time file cannot be published in the feed and profile. Choose link access or turn off the one-time link.
`UPLOAD_FORMAT_UNSUPPORTED`	400	Supported formats are still PNG, JPEG, WebP and AVIF images, plus MP4 and WebM video. Images can contain up to 40 megapixels.
`VALIDATION_FAILED`	400	Check the form fields.
`ACCOUNT_ACCESS_CHANGED`	401	Account access has changed. Sign in again.
`ACCOUNT_BANNED`	401	This account has been suspended by an administrator.
`API_KEY_EXPIRED`	401	The API key has expired. Create a new key or connect the app again.
`API_KEY_INVALID`	401	The API key is invalid.
`API_KEY_REVOKED`	401	The API key has been revoked. Create a new key or connect the app again.
`BEARER_REQUIRED`	401	A Bearer key is required.
`DEVICE_KEY_REQUIRED`	403	Only the key of an app connected through the browser can renew itself.
`ORIGIN_FORBIDDEN`	403	The request origin is not allowed.
`PLAN_FEATURE_REQUIRED`	403	This is available in Pro.
`SCOPE_REQUIRED`	403	The API key does not have the required permission.
`ACCOUNT_UNAVAILABLE`	404	The account is unavailable.
`UPLOAD_STALLED`	408	The file stopped arriving. Check your connection and upload it again.
`DEVICE_RENEW_TOO_EARLY`	409	The connection can be renewed within 30 days of its end.
`PASTE_REVISION_CONFLICT`	409	The note changed in another tab. Compare your draft with the server version.
`FOLDER_TOO_LARGE`	413	The folder has more than 20 MB of text. Choose a smaller folder or exclude files in .gitignore.
`FOLDER_TOO_MANY_FILES`	413	Up to 2,000 files can be shared. Choose a smaller folder or exclude files in .gitignore.
`IMAGE_TOO_LARGE`	413	The image exceeds the size limit. Compress it or reduce its resolution.
`QUOTA_EXCEEDED`	413	There is not enough storage in the account.
`UPLOAD_TOO_LARGE`	413	The file exceeds the size limit.
`VIDEO_TOO_LARGE`	413	The video exceeds the size limit. Make it smaller with Compress in your lacuna console or the Windows app.
`VIDEO_NOT_SUITABLE`	415	The video must be compressed before upload: lacuna keeps H.264 with AAC (MP4) or VP9/AV1 with Opus (WebM) up to 3840 × 2160. Compress it in the lacuna app for Windows or in Compress on the site.
`FOLDER_INFECTED`	422	The antivirus found a threat in the folder, so it was not uploaded.
`RATE_LIMITED`	429	Too many requests. Try again later.
`UPLOAD_USER_BUSY`	429	Your account already has uploads in progress. The next one starts when one of them finishes.
`SERVICE_UNAVAILABLE`	503	The service is temporarily unavailable. Try again later.
`UPLOAD_SERVER_BUSY`	503	The server is receiving many files right now. Try again in a few seconds.