HomeGuidesAPI ReferenceChangelogDiscussions
Hire a ReactVision Expert 🛠️Launch Studio 🖥️Sponsor on GitHub ❤️Log In
API Reference

Errors

Response format

Every response is JSON and carries meta.request_id, except a successful Advanced VPS response, which is the documented shape alone. Quote it to support about a request. An error is:

{
  "error": { "code": "ANCHOR_NOT_FOUND", "message": "Anchor not found" },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Branch on error.code, not on error.message, which may be reworded. Some successful responses also carry "success": true; each operation's schema shows its shape.

Ids your key cannot reach

An id your key cannot reach, because it belongs to another team or, for a bound key, to another project, is answered exactly like an id that does not exist:

  • An id in the path answers 404 with the resource's not-found code: ANCHOR_NOT_FOUND, SCENE_NOT_FOUND, PROJECT_NOT_FOUND, ASSET_NOT_FOUND. For a client key, a private cloud anchor answers the same.
  • A project_id in the query or the body answers 403 PROJECT_NOT_FOUND, also for a project that does not exist.
  • A linked scene, scene asset, team asset or file in a body answers 404 SCENE_NOT_FOUND, SCENE_ASSET_NOT_FOUND, TEAM_ASSET_NOT_FOUND or USER_ASSET_NOT_FOUND.
  • A scene's API request function answers 404 FUNCTION_NOT_FOUND.

Three groups answer differently. The co-location room and Advanced VPS operations answer 403: PROJECT_NOT_FOUND for a project that does not exist and PROJECT_ACCESS_DENIED for one the key cannot reach, because the native SDK reads a 404 there as a missing deployment and keeps retrying. The Advanced VPS operations answer 404 NOT_FOUND for a location or scan the request cannot see. The AI operations answer 403 PROJECT_ACCESS_DENIED or SCENE_ACCESS_DENIED for a project or scene the key cannot reach, and 403 ACCESS_DENIED for a task of another team or project.

Codes

Every operation lists the codes it can return. All of them:

CodeStatusMeaning
MISSING_API_KEY401No x-api-key header (and, on the Advanced VPS operations, no user token).
MISSING_AUTH401No x-api-key header and no other credential (scenes, projects, scene API requests, AI).
INVALID_API_KEY_FORMAT401The key is not rv_live_, rv_client_ or rv_secret_ followed by 64 lowercase hexadecimal characters.
INVALID_API_KEY401No such key, or a key sent with the wrong prefix for its type.
API_KEY_EXPIRED401The key is past its expiry date.
AUTH_ERROR401A user token (rv_ut_) was sent where it is not accepted.
INVALID_SESSION401An Authorization: Bearer header that is not a valid ReactVision Editor session. Send the key in x-api-key instead.
INVALID_SESSION_FORMAT401Advanced VPS: the Authorization header is not Bearer followed by a user token.
INVALID_APP_USER_TOKEN401The user token is not valid, or the secret key that minted it has been deleted or has expired.
APP_USER_TOKEN_EXPIRED401The user token has expired. Get a new one from your backend.
APP_USER_TOKEN_SCOPE_NOT_ALLOWED403The user token does not carry the operation's scope. A new token from the same key carries the same scopes.
APP_USER_TOKEN_NOT_ALLOWED403Co-location: a user token emptying a room's saved state.
APP_USER_TOKEN_REQUIRED403Co-location: a client or legacy key, once ReactVision stops accepting them there (no date is set yet). Use a user token, or a secret key.
API_KEY_TYPE_NOT_ALLOWED403The operation does not accept this type of key.
API_KEY_SCOPE_NOT_ALLOWED403The secret key was created without the operation's scope (see Scopes).
APP_USER_ID_NOT_ALLOWED403Advanced VPS: a client or legacy key sent x-app-user-id. Use a user token, or a secret key on your backend.
APP_USER_MISMATCH403Advanced VPS: a user token sent another app user's x-app-user-id or asked to delete another app user's data, or a secret key sent x-app-user-id and asked to delete another app user's data.
API_KEY_LOOKUP_FAILED503The key could not be checked. Retry; the key is not invalid.
RATE_LIMITED429Over a rate limit. Wait the seconds in Retry-After.
API_REQUEST_LIMIT_REACHED403The team's monthly API request quota is used up.
STORAGE_LIMIT_REACHED403The team's storage quota is used up.
LIMIT_REACHED403The team's monthly AI credit budget would be exceeded, or could not be read.
PAID_PLAN_REQUIRED403Co-location, and creating Advanced VPS locations and scans and uploading their recordings, need a paid plan.
COMPUTE_BILLING_NOT_SET_UP403Advanced VPS endpoints only: the team's plan has no payment method that can be charged for compute time.
COMPUTE_PAYMENT_FAILED403Advanced VPS endpoints only: the team's last compute usage invoice is unpaid.
COMPUTE_SPEND_LIMIT_REACHED403Advanced VPS endpoints only: this usage period's compute spend is at the team's limit.
VPS_SHARED_LOCATION403Advanced VPS: an app user changing a shared location or scan.
PROJECT_NOT_FOUND403 or 404The project does not exist or the key cannot reach it. 404 when the project id is in the path.
PROJECT_ACCESS_DENIED403Co-location, Advanced VPS and AI: the key cannot reach the project, or it is not the user token's project.
SCENE_ACCESS_DENIED403AI: the key cannot reach the scene.
ACCESS_DENIED403AI: the task belongs to another team or project, or a bound key sent neither project_id nor scene_id.
DRY_RUN_JWT_ONLY403A scene API request sent with dry_run: true, which only the Editor may send.
PROJECT_LOOKUP_FAILED503The project could not be checked. Retry.
TIER_LOOKUP_FAILED503The team's plan could not be checked. Retry.
ANCHOR_NOT_FOUND404No such anchor, or one the key cannot reach.
SCENE_NOT_FOUND404No such scene, or one the key cannot reach.
SCENE_ASSET_NOT_FOUND404No such scene asset in the anchor's project.
TEAM_ASSET_NOT_FOUND404No such team asset, or one of another team.
USER_ASSET_NOT_FOUND404No such file, or one the key cannot reach.
ASSET_NOT_FOUND404No such file, or one the key cannot reach.
FUNCTION_NOT_FOUND404No such API request function, or one the key cannot reach.
TASK_NOT_FOUND404No such AI task.
ROOM_NOT_FOUND404No such co-location room or join code in this project.
NOT_FOUND404No such operation: check the path. On the Advanced VPS operations, also a location or scan that does not exist or that the request cannot see.
NO_ASSET404Advanced VPS: the location's active scan, or the scan, has no file of that kind.
METHOD_NOT_ALLOWED405The path exists, but not with this HTTP method.
TOO_MANY_ROOMS409The project already holds 500 co-location rooms.
ALREADY_UPLOADED409Advanced VPS: the scan is no longer awaiting_upload.
RECORDING_NOT_UPLOADED409Advanced VPS: an upload completed before it was admitted, or before the recording was stored.
TOO_LARGE413Advanced VPS: a JSON body over 64 KB, or a recording over 512 MiB.
VPS_USER_LIMIT_REACHED429Advanced VPS: the app user has started as many scans today (UTC) as the team allows, 10 unless the team set its own limit.
VPS_USER_OPEN_SCANS_LIMIT429Advanced VPS: the app user already has 3 scans waiting to be uploaded or processed.
VPS_QUEUE_FULL429Advanced VPS: 50 scans of the team are already waiting to be processed.
SCENE_BOUND_TO_VPS409Co-location: the room's scene is bound to an Advanced VPS location, which a co-location room cannot share.
CONTENT_REFUSED422The image model refused the prompt. Reword it.
SCENE_REQUIRES_VPS_RUNTIME426The scene is bound to an Advanced VPS location and the request did not send x-rv-capabilities: vps.
MISSING_FIELD400A required body field is missing; the message names it.
MISSING_PROJECT_ID400project_id (or the x-project-id header) is required.
INVALID_PROJECT_ID400x-project-id is not a UUID.
INVALID_BODY400The body is not valid JSON or not an object, or a field failed its check; the message says which.
BAD_REQUEST400Advanced VPS: the body is not a JSON object, or a field or parameter is missing or out of range; the message names it.
RECORDING_SIZE_MISMATCH400Advanced VPS: the stored recording is not the recording_bytes its upload declared. It was removed: upload it again.
INVALID_REQUEST400Scene API requests: the body is not valid JSON or a field failed its check.
INVALID_FIELD_VALUE400A field has the wrong type, a field that cannot be cleared was sent as null, or a client key sent a field it may not set.
FIELD_TOO_LONG400A text field is over its length limit, or a JSON object is over 4096 bytes.
NO_UPDATES400An update named no field it can change.
INVALID_LATITUDE, INVALID_LONGITUDE400Outside -90 to 90, or -180 to 180.
MISSING_COORDINATES400A nearby search without lat and lng.
INVALID_ALTITUDE, INVALID_ALTITUDE_MODE400Geospatial alt or altitude_mode out of range.
INVALID_PLATFORM400platform is not ios, android or web.
INVALID_KEYPOINTS, KEYPOINT_COUNT_MISMATCH400Cloud anchor keypoints_json is malformed, or keypoint_count does not match it.
INVALID_DESCRIPTORS_URL, INVALID_FEATURE_POINTS_URL, INVALID_MESH_URL, INVALID_FILE_URL400The URL is not a file this project uploaded through POST /assets/upload.
FILE_NOT_FOUND400file_url names no stored file.
INVALID_ASSET_TYPE, INVALID_ASSET_REFERENCE400An unknown asset_type, or no asset to attach.
USER_ASSET_PROJECT_MISMATCH400The file belongs to another project of the team.
INVALID_CONTENT_TYPE, INVALID_FORM_DATA, MISSING_FILE, FILE_TOO_LARGE, INVALID_FILE_TYPE400An upload that is not multipart, has no file, or whose file is too large or of a type the asset_type does not allow.
APP_USER_ID_TOO_LONG, INVALID_APP_USER_ID400app_user_id (or x-app-user-id) is over 255 characters, or not printable ASCII without spaces.
INVALID_SCENE_ID400A scene id that is not a UUID, or not a scene of this project (co-location).
MISSING_PROMPT, PROMPT_TOO_LONG, INVALID_MODEL, INVALID_QUALITY, INVALID_TYPE, INVALID_COMBINATION, MISSING_IMAGE, IMAGE_TOO_LARGE, INVALID_IMAGE_TYPE, INVALID_IMAGE_URL, INVALID_REFERENCE_IMAGE_URL, INVALID_SCENE400AI request checks; each AI operation explains them.
GENERATION_FAILED, SERVICE_ERROR502The AI provider failed. Nothing is charged; a retry may succeed.
SERVICE_NOT_CONFIGURED, APP_USER_TOKEN_SIGNING_UNAVAILABLE503A ReactVision service is unavailable. Retry later.
GENERATION_UNAVAILABLE503AI image generation: the provider is unavailable on ReactVision's side. Nothing is charged. Retry later, not right away.
AUTH_UNAVAILABLE503Advanced VPS: the key or user token could not be checked. Retry; it is not invalid.
VPS_LOOKUP_FAILED, COMPUTE_BILLING_UNAVAILABLE503Advanced VPS: the records, or the team's billing, could not be read. Retry.
CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, LIST_FAILED, NEARBY_SEARCH_FAILED, RESOLVE_TRACKING_FAILED, ATTACH_ASSET_FAILED, REMOVE_ASSET_FAILED, ASSET_CREATE_FAILED, UPLOAD_FAILED, LOOKUP_FAILED, RESET_FAILED500The operation failed on our side. Retry.
INTERNAL_ERROR500An unexpected error. Retry, and quote meta.request_id to support if it persists.

A 503 is never a decision about your key or your request: retry it. A 401 or 403 is, and retrying the same request will not change it.