Errors

Every failed REST request returns the same error envelope and an HTTP status that matches the failure. Clients can dispatch on the status without parsing the body, and read code when they need to react to a specific failure.

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 HTTP status shown, except where an entry names a second status. HTTP status mapping lists the same failures by status.

UNAUTHENTICATED

401. The Authorization header is missing or not in Bearer <key> form, or it carries an OAuth access token that is invalid, expired, or revoked.

INVALID_API_KEY

401. The bearer token does not match a key in the target organization, or the key's organization no longer exists.

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.

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. A key that cannot reach a specific library gets API_KEY_NOT_AUTHORIZED_FOR_LIBRARY (404) instead.

FORBIDDEN

403. An OAuth access token tried to create a library, and its account is not an Owner of the organization. See POST /organizations/:orgId/libraries. Also returned by PATCH …/assets/:assetId/approval when setting approval is not available to the token's account.

APPROVAL_REQUIRES_USER

403. An API key tried to set an asset's approval. Setting approval needs an OAuth access token; an API key can still read approval. See PATCH …/assets/:assetId/approval.

PAID_PLAN_REQUIRED

403. Setting an asset's approval needs a paid plan, and the organization has none. Upgrade the organization to Pro. Reading approval is unaffected.

ORGANIZATION_NOT_FOUND

404. The :organizationId path segment does not resolve to a known org. An OAuth access token gets this code when listing or creating libraries and when searching; on an endpoint under a library it gets API_KEY_NOT_AUTHORIZED_FOR_LIBRARY (404). An API key gets INVALID_API_KEY (401).

RESOURCE_NOT_FOUND

404. The asset a read names, or a variant upload's parentId, does not exist. Tagging, untagging, transferring, deleting, and setting a description or approval return BAD_USER_INPUT (400) for an asset that is not in the library. A promote returns NOT_FOUND instead.

NOT_FOUND

404. The variant a promote names is not in the library, or is in the trash. See POST …/assets/:assetId/promote.

ENDPOINT_NOT_FOUND

404. The REST path itself is unknown, which is 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).

Also returned when an upload carries no file part or more than 20 files, and when a delete request's ids is missing, empty, or holds more than 100 ids.

Also returned when no file in an upload is accepted. The message gives the reason: for one file, the reason itself (e.g. Unsupported file type for photo.jfif); for several, each file name followed by its reason. A file's type is unsupported when Raster recognizes neither its extension nor its declared content type. An image whose bytes cannot be read is refused too (photo.png can't be opened. It may be damaged.), and nothing is stored for it.

Also returned for a state the organization does not use on PATCH …/assets/:assetId/approval, and for an unknown approval filter on GET …/search/assets.

An OAuth access token limited to one organization gets this code with status 403 when the request addresses a different organization.

PAYLOAD_TOO_LARGE

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

LIBRARY_URL_TAKEN

409. The slug passed to POST /organizations/:orgId/libraries is already taken by another library in the organization. Choose a different slug.

CONFLICT

409. A promote is already running on the asset. Wait for it to finish, then retry. See POST …/assets/:assetId/promote.

PRO_PLAN_CANCELED

403. The organization's Pro plan has ended and the organization still has more than one member. Reactivate the subscription, or reduce the organization to a single member to continue on the Free plan. Returned for uploads and for library creation. An organization already down to a single member keeps the ordinary Free-plan limits instead.

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.

LIBRARY_LIMIT_EXCEEDED

400. An organization on the Free plan already has 3 or more libraries and tried to create another. Upgrade the organization to Pro to create more.

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.

SERVICE_UNAVAILABLE

503. An OAuth access token could not be verified because the authorization service is temporarily unavailable. Retry the request with backoff, using the same token.

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": "Missing required header. Set \"Api-Version: 2026-07-08\"."
  }
}

Missing API key:

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

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "No credential 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."
  }
}