Platform

Error responses (RFC 9457)

Most of /api/v1 uses a shared RFC 9457-style problem shape. Application errors render as application/json and transport-level failures render as application/problem+json. Partner and engagement planes under /api/v1 return a bare {error: code} body instead. SCIM keeps its separate application/scim+json error format.

API docs

Browse docs

On this page

01 Error schema

details

Top-level fields

Problem responses include type (error URI), title, status, detail, and request_id. Type-specific context may appear in extra. SCIM errors do not use this schema.

02 Common error types

reference

Status	Type URI	Title
400	problems/bad-request	Bad request
401	problems/unauthorized	Unauthorized
402	problems/payment-required	Workspace credits are insufficient; extra.payment_intent is the checkout intent
403	problems/forbidden	Forbidden
404	problems/not-found	Not found
406	problems/not-acceptable	Not acceptable
409	problems/conflict	Conflict
410	problems/enrollment-expired	This enrollment token has expired
410	problems/robot-decommissioned	The robot is retired; the claim or device write is refused
415	problems/unsupported-media-type	Unsupported media type
422	problems/unprocessable-entity	Unprocessable entity
429	problems/rate-limited	Rate limited
429	problems/quota-exceeded	Plan quota exceeded; extra carries upgrade, resource, plan, limit, usage
500	problems/internal-server-error	Internal server error

03 Example error response

example

{
  "type": "https://robotscenter.net/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "Resource not found",
  "request_id": "req-01HQ5PX7P7F4"
}

04 Extra context

details

403 Forbidden

extra.required_scopes lists the scopes needed to access the resource. Workspace gates also set a top-level error of workspace_frozen, workspace_paused, or workspace_archived before any controller runs.

422 Validation

extra.errors is an object keyed by field; each value is an array of validation messages. It is not an array of {field, message} objects.

429 Rate limited or quota

Rate limits set extra.retry_after_seconds. Quota failures use type problems/quota-exceeded and extra.upgrade, extra.resource, extra.plan, extra.limit, and extra.usage.

05 Surfaces that do not use problem JSON

details

Partner and engagement planes

Routes under /api/v1/partner and POST /api/v1/engagements/:engagement_id/events return a bare {"error": "code"} body for 401, 403, 404, 409, 413, and 422. They do not use the RFC 9457 problem shape that the rest of /api/v1 uses.

SCIM

SCIM keeps application/scim+json errors. Last-owner and uniqueness conflicts are HTTP 409 with that SCIM media type.

06 Validation error example (422)

example

{
  "type": "https://robotscenter.net/problems/unprocessable-entity",
  "title": "Unprocessable entity",
  "status": 422,
  "detail": "Validation failed",
  "request_id": "req-01HQ5PX7P7F4",
  "extra": {
    "errors": {
      "url": ["must be an absolute http(s) URL"],
      "event_types": ["should have at least 1 item(s)"]
    }
  }
}

Related docs