Get started

Authentication and errors

Partner keys, the error envelope, and every error code.

Authentication (you calling us)

One long-lived bearer partner key, issued by RapidEye when we set you up:

Text

Authorization: Bearer rapideye_pk_...

Server-side secret only; never ship it to a browser or mobile client. Unknown key gets 401 invalid_key; revoked key gets 403 key_revoked; an integration we have paused gets 403 partner_disabled, which is not a problem with the key and is not fixed by rotating one.

Every non-2xx response uses one envelope; branch on error.code, not message text:

JSON

{ "error": { "code": "workspace_not_provisioned", "message": "..." } }

code and message are always present. detail and next_steps are optional and are omitted entirely when they do not apply, never sent as null or as an empty object, so test for the key before reading it. workspace_not_provisioned above carries no specifics, which is why it has neither.

When detail is present it is an object carrying the machine-actionable specifics for that code (which parameter was missing, which limit was exceeded, which property id was not in the roster). Its keys vary by code, so read them per code rather than assuming a fixed shape.

Error codes

Every code this surface emits. The status is part of the contract too: branch on the code, and treat any code you do not recognize as a failure of its status class.

Code	Status	Meaning
`missing_parameter`	400	A required parameter, field or header is absent or blank. `detail.parameter` names it.
`invalid_request`	400	The body is unusable, or a field is: malformed JSON, not a JSON object, wrong type, too long, an unknown field, or not yours to set. When one field is at fault `detail.parameter` names it, and a roster item problem also carries `detail.index`. A refused `return_url` also carries `detail.reason`: `not_allowed` or `malformed`.
`invalid_email`	400	The address on a workspace claim is not one we can send to.
`invalid_key`	401	The `Authorization` header is missing, malformed, or carries a key we do not recognize. A configuration bug on your side; stop and check the key.
`key_revoked`	403	The key was valid and we turned it off. Not a configuration bug; email support for a replacement.
`partner_disabled`	403	Either the whole integration is paused on our side, or we hold no registry row for your slug at all. Your key is not the problem and a new one will not change the answer. Email support.
`not_found`	404	No such path on this API, or no such `inspection_id` or `import_id` in that workspace. Also what you get for a resource belonging to a different workspace; we do not distinguish the two.
`workspace_not_provisioned`	404	That workspace id is not provisioned for you. Create it with `POST /v1/workspaces`.
`task_not_found`	404	No recording link has been issued for that `task_id` in that workspace. Call `GET /v1/recording-link` first.
`property_not_found`	404	That `property_id` is not in the workspace's roster. Send a roster that contains it. We do not create properties from a link request.
`method_not_allowed`	405	The path exists; the verb does not. `detail.allowed_methods` lists the ones that do.
`claim_requires_admin`	409	`POST /v1/workspace-claims` on a workspace your key did not create, or one that already has people in it. Ask RapidEye to nominate the owner.
`workspace_already_claimed`	409	The workspace already has an owner. They manage their own team from Settings; nothing for you to do.
`report_not_ready`	409	The inspection exists but has no released report yet, so it has no findings. Wait for `inspection.completed`; do not treat this as a permanent failure.
`video_not_ready`	409	The inspection's video is not recorded yet, still being processed, or being recorded again. Call again after `inspection.recording_completed` or `inspection.completed`. Not a permanent failure.
`video_not_available`	404	The inspection has no video to download: it was a photo inspection, or its recording could not be processed. This answer rarely changes, so do not poll for it.
`roster_required`	409	No roster has been confirmed for this workspace yet, so no recording links can be issued. Send one to `POST /v1/roster-imports`.
`property_inactive`	409	The property is in the roster but was not in the most recent snapshot you sent, so it is marked inactive. Include it in your next import to bring it back.
`property_not_activated`	409	The property is in the roster but is not switched on for inspections. Properties switch on a few seconds after an import applies, so if the import has only just applied, wait and retry. Otherwise send the roster again with a new `Idempotency-Key` (or trigger a sync with `POST /v1/roster-syncs` if you host a feed). If this persists, email support.
`workspace_not_enabled`	409	The account exists and inspections are not switched on for it. The account switches on when a roster import applies, so send the roster again with a new `Idempotency-Key` (or trigger a sync with `POST /v1/roster-syncs` if you host a feed). If this persists, email support.
`task_property_conflict`	409	That `task_id` already has a link for a different property. A task is bound to one property for its whole life. Use a new `task_id`.
`idempotency_conflict`	409	That `Idempotency-Key` was already used for a different roster. Reuse a key only to retry the identical request.
`roster_revision_conflict`	409	The import was built on a roster revision that is no longer current, because another import landed first. Re-read `GET /v1/properties` and send a fresh snapshot with a new `Idempotency-Key`. Appears on the run, in `error.code`.
`roster_empty_not_allowed`	409	The import carries no properties. An empty roster retires every door, so it is never implicit: re-send with `allow_empty: true` and a new `Idempotency-Key`. Appears on the run, in `error.code`.
`roster_confirmation_required`	409	The import would deactivate more than half of the present properties. Re-send with `acknowledge_inactive_count` set to the count in `detail` and a new `Idempotency-Key`. Appears on the run, in `error.code`.
`roster_duplicate_property`	409	A `property_id` appeared twice in one roster. Appears on the run, in `error.code`, for a feed we pulled. A pushed body gets `400 invalid_request` with the repeated ids in `detail.duplicate_property_ids`.
`pull_not_configured`	409	This workspace pushes its roster; there is no feed for us to poll.
`matterport_import_in_progress`	409	A Matterport tour is still importing for this home: a different tour on `PUT .../matterport` (`detail.importing` names it), or any tour on `POST .../baseline-photos`, because a home runs one import at a time. `detail.import_id` names the running import. Wait for `setup.matterport.state` to leave `importing`, then send again.
`baseline_import_in_progress`	409	A baseline photo import is still running for this home, yours or one its managers started, so a new photo batch or a new tour waits: a home runs one import at a time. When the running import is yours, `detail.import_id` names it; one a manager started has no id you can read. Send again once `setup.baseline_photos.state` leaves `importing`.
`workspace_already_claimed`	409	An owner has already claimed this workspace.
`claim_requires_admin`	409	This workspace is not one you may nominate an owner for. Email support.
`payload_too_large`	413	The request body exceeds the endpoint's cap. `detail.limit_bytes` names it.
`too_many_requests`	429	Too many requests in a short window. Back off and retry; nothing is lost. Provisioning, roster imports, claims and manual syncs each have their own tighter bound.
`internal_error`	500	Something broke on our side. The request was not processed; retrying is safe.
`service_unavailable`	503	A dependency of ours is failing, including the one that verifies your key. Not a problem with the key; never roll a key in response to this.