Errors

Every failed REST request returns a uniform error envelope and a meaningful HTTP status. The status is the primary signal — clients can dispatch on it without parsing the body. The code is the secondary signal for clients that need to react to a specific failure mode.

The error envelope

Every failure body is shaped the same way:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message safe to surface to end users."
  }
}

The envelope is stable across every endpoint, including auth rejections and unknown-path 404s.

HTTP status mapping

Error codes

Every failure carries one of these codes in error.code. Each maps to the fixed HTTP status shown — see HTTP status mapping for the status-first view.

UNAUTHENTICATED

401. The Authorization header is missing or not in Bearer <key> form.

INVALID_API_KEY

401. The bearer token does not match a key in the target organization.

API_VERSION_REQUIRED

400. The Api-Version header is missing or empty.

API_KEY_NOT_AUTHORIZED_FOR_LIBRARY

404. The key cannot reach the target library — either because the library does not exist or because the key has not been granted access to it. Returns 404 rather than 403 to avoid revealing the existence of libraries the key has no access to.

API_KEY_READ_ONLY

403. The key is read-only — it has no write access to any library — and tried to create a library. Creating a library grants it to the calling key, so it requires a key with write access. Distinct from API_KEY_NOT_AUTHORIZED_FOR_LIBRARY (404) so a client can tell "this key can't write anywhere" apart from "this key can't reach that library."

ORGANIZATION_NOT_FOUND

404. The :organizationId path segment does not resolve to a known org.

RESOURCE_NOT_FOUND

404. The asset referenced by the request does not exist.

ENDPOINT_NOT_FOUND

404. The REST path itself is unknown — distinct from a missing resource.

BAD_USER_INPUT

400. The request body or params are invalid. Includes malformed JSON. Also returned by POST /libraries for invalid input (e.g. a bad email or an exhausted per-email creation quota).

PAYLOAD_TOO_LARGE

413. A file in the upload exceeds the per-file size limit.

MAX_ASSETS_EXCEEDED

400. The upload contains more than 20 files, or the delete batch exceeds 100 ids.

UPLOAD_ERROR_NO_FILES

400. The upload request carries no usable file parts.

DELETE_ERROR

400. The delete request is missing ids or ids is empty.

PRO_PLAN_CANCELED

403. The organization's Pro subscription has been canceled. Renew it to upload again.

STORAGE_LIMIT_EXCEEDED

403. The organization's Free plan storage cap of 1 GB is reached.

LIBRARY_LOCKED

403. The target library is locked because the Free plan only includes the first 3 libraries.

EPHEMERAL_STORAGE_LIMIT_EXCEEDED

403. An unclaimed temporary library has reached its storage cap. Claim it to a Raster account to keep uploading.

EPHEMERAL_LIBRARY_LIMIT_EXCEEDED

400. A temporary (unclaimed) library cannot create additional libraries. Claim it to a Raster account first.

INTERNAL_SERVER_ERROR

500. An unexpected server fault. Safe to retry with backoff.

Example failure responses

Missing Api-Version header:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Vary: Api-Version

{
  "error": {
    "code": "API_VERSION_REQUIRED",
    "message": "The Api-Version header is required (current: 2026-05-20)."
  }
}

Missing API key:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Vary: Api-Version

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "API Key not provided."
  }
}

Unknown REST path:

HTTP/1.1 404 Not Found
Content-Type: application/json
Vary: Api-Version

{
  "error": {
    "code": "ENDPOINT_NOT_FOUND",
    "message": "The requested REST endpoint does not exist."
  }
}